@openmixer/omx-dsp 0.28.0 → 0.29.0

package/dist/definitions.d.ts

@@ -2,3 +2,24 @@
 export declare const RTA_TARGET_BIN_HZ = 5.9;
 /** The largest RTA FFT the native ring holds — generated into `omx_contract_limits.h` as `OMX_RTA_FFT_SIZE_MAX`. @see data/kernels/rta.json */
 export declare const RTA_FFT_SIZE_MAX = 32768;
+/** Where the low-pass section hands its poles over from the matched pair to the prewarped bilinear pair, as fractions of Nyquist, and how that band moves with Q. At `qHi` (1/sqrt(2), the 12 dB Butterworth) the band runs from `loAtHiQ` to `hiAtHiQ`; at `qLo` (0.5412, the low-Q half of the 24 dB Butterworth) and below, from `loAtLoQ` to `hiAtLoQ`; between the two it moves linearly. Above `qHi` the prototype peaks, and the band's end moves down to `hiAtPeakQ` by `qPeak`, held above it. Below the band the low-pass is the matched design unchanged. @see data/kernels/eq.json */
+export declare const LOWPASS_HANDOVER: {
+    readonly qHi: 0.7071067811865476;
+    readonly qLo: 0.541196100146197;
+    readonly qPeak: 0.9;
+    readonly loAtHiQ: 0.6;
+    readonly hiAtHiQ: 0.85;
+    readonly loAtLoQ: 0.8;
+    readonly hiAtLoQ: 0.9;
+    readonly hiAtPeakQ: 0.8;
+};
+/** The Q (resonance) extent of a parametric band. @see data/kernels/eq.json */
+export declare const EQ_Q_RANGE: {
+    readonly min: 0.3;
+    readonly max: 8;
+};
+/** The Q extent of a NOTCH band. Wider than EQ_Q_RANGE on purpose (#116, operator decision): an ultra-narrow surgical cut is the notch shape's whole point — the FBS ring-out pool plants dbx-AFS-style ring killers at Q ≈ 116 (~1/80 octave), inaudible on program yet fatal to a single ringing frequency. Gain-carrying shapes stay bounded at EQ_Q_RANGE — a Q-116 bell is a resonator, not an EQ move. @see data/kernels/eq.json */
+export declare const EQ_NOTCH_Q_RANGE: {
+    readonly min: 0.3;
+    readonly max: 116;
+};

package/dist/definitions.js

@@ -5,3 +5,18 @@
 export const RTA_TARGET_BIN_HZ = 5.9;
 /** The largest RTA FFT the native ring holds — generated into `omx_contract_limits.h` as `OMX_RTA_FFT_SIZE_MAX`. @see data/kernels/rta.json */
 export const RTA_FFT_SIZE_MAX = 32768;
+/** Where the low-pass section hands its poles over from the matched pair to the prewarped bilinear pair, as fractions of Nyquist, and how that band moves with Q. At `qHi` (1/sqrt(2), the 12 dB Butterworth) the band runs from `loAtHiQ` to `hiAtHiQ`; at `qLo` (0.5412, the low-Q half of the 24 dB Butterworth) and below, from `loAtLoQ` to `hiAtLoQ`; between the two it moves linearly. Above `qHi` the prototype peaks, and the band's end moves down to `hiAtPeakQ` by `qPeak`, held above it. Below the band the low-pass is the matched design unchanged. @see data/kernels/eq.json */
+export const LOWPASS_HANDOVER = {
+    qHi: 0.7071067811865476,
+    qLo: 0.541196100146197,
+    qPeak: 0.9,
+    loAtHiQ: 0.6,
+    hiAtHiQ: 0.85,
+    loAtLoQ: 0.8,
+    hiAtLoQ: 0.9,
+    hiAtPeakQ: 0.8,
+};
+/** The Q (resonance) extent of a parametric band. @see data/kernels/eq.json */
+export const EQ_Q_RANGE = { min: 0.3, max: 8 };
+/** The Q extent of a NOTCH band. Wider than EQ_Q_RANGE on purpose (#116, operator decision): an ultra-narrow surgical cut is the notch shape's whole point — the FBS ring-out pool plants dbx-AFS-style ring killers at Q ≈ 116 (~1/80 octave), inaudible on program yet fatal to a single ringing frequency. Gain-carrying shapes stay bounded at EQ_Q_RANGE — a Q-116 bell is a resonator, not an EQ move. @see data/kernels/eq.json */
+export const EQ_NOTCH_Q_RANGE = { min: 0.3, max: 116 };

package/dist/eq.d.ts

@@ -1,3 +1,82 @@
-/** The twin of omx_eq_design.h omx_eq_octaves_q, moved verbatim from the console (its catalog package). */
-/** Bandwidth in octaves → Q (the cookbook relation). */
+/** Bandwidth in octaves → Q (the cookbook relation). The twin of omx_eq_octaves_q. */
 export declare function octavesToQ(octaves: number): number;
+/**
+ * A band's Q clamped into the extent its shape allows: a notch may go ultra-narrow ({@link EQ_NOTCH_Q_RANGE}),
+ * every other shape keeps {@link EQ_Q_RANGE}. The twin of omx_eq_lv2_clamp_q, which clamps a float.
+ * @param type The band shape; only `'notch'` takes the notch range.
+ * @param q The asked Q.
+ */
+export declare function clampEqQFor(type: string, q: number): number;
+/** The section kinds of omx_eq_design, by the twin's word (omx_eq_kind 0..8 in this order). */
+export type BiquadKind = 'peaking' | 'lowShelf' | 'highShelf' | 'highpass' | 'lowpass' | 'notch' | 'bandpass' | 'allpass1' | 'allpass2';
+/** One designed section, `a0` carried explicitly (every design here normalises, so it is 1). */
+export interface BiquadSection {
+    readonly b0: number;
+    readonly b1: number;
+    readonly b2: number;
+    readonly a0: number;
+    readonly a1: number;
+    readonly a2: number;
+}
+/**
+ * The low-pass hand-over band for a Q, as fractions of Nyquist: the matched poles below the first, the bilinear
+ * pair from the second. The twin of omx_eq_lowpass_handover; the table is {@link LOWPASS_HANDOVER}.
+ */
+export declare function lowpassHandover(q: number): readonly [number, number];
+/**
+ * One conjugate pair placed by the matched-Z map `z = exp(sT)`: the digital pair `1 + p1 z^-1 + p2 z^-2` of the
+ * analogue `s^2 + 2 zeta wn s + wn^2`, and `dc`, that polynomial at `z = 1` in a factored form that does not
+ * cancel for a low section. `wn` (radians per sample) is held at or below pi.
+ * @param wn The pair's centre, `2 pi f / fs`.
+ * @param zeta The damping, `1/(2Q)` for a plain resonator.
+ */
+export declare function matchedPair(wn: number, zeta: number): {
+    p1: number;
+    p2: number;
+    dc: number;
+};
+/**
+ * One section as omx_eq_design designs it: matched-Z peaking and shelves, a matched low-pass with its fitted
+ * numerator and Nyquist hand-over, a matched notch under the cookbook numerator, the cookbook high-pass and
+ * bandpass, and the first- and second-order allpasses. The centre is clamped to `[1, 0.999 Nyquist]` and a Q at
+ * or under 0 is taken as 1e-3; `gainDb` is read by the peaking and shelf kinds only.
+ * @param kind The section kind.
+ * @param freqHz Centre or corner, Hz.
+ * @param q Quality factor.
+ * @param gainDb Gain, dB.
+ * @param sampleRate Rate the section runs at, Hz.
+ */
+export declare function rbjSection(kind: BiquadKind, freqHz: number, q: number, gainDb: number, sampleRate: number): BiquadSection;
+/**
+ * The magnitude of one designed section at `freq`, dB, by the unit-circle arithmetic itself. A point at or above
+ * Nyquist, or a degenerate denominator, is 0 dB; a full null floors at `floorDb`.
+ * @param section The section.
+ * @param freq Probe frequency, Hz.
+ * @param fs Sample rate, Hz.
+ * @param floorDb The floor of a null, dB.
+ */
+export declare function sectionMagnitudeDb(section: BiquadSection, freq: number, fs: number, floorDb: number): number;
+/** The shapes a drawn band takes: the plugin and surface spelling. */
+export type BiquadType = 'bell' | 'lowshelf' | 'highshelf' | 'highpass' | 'lowpass' | 'notch' | 'allpass1' | 'allpass2';
+/** One drawn band in engineering units. */
+export interface BiquadBand {
+    readonly type: BiquadType;
+    /** Centre or corner, Hz. */
+    readonly freq: number;
+    /** Gain, dB (bell and shelves only). */
+    readonly gainDb: number;
+    /** Quality factor. */
+    readonly q: number;
+}
+/**
+ * One band's magnitude at `freq`, dB: {@link rbjSection} evaluated by {@link sectionMagnitudeDb}. The twin of
+ * omx_eq_band_magnitude_db.
+ * @param floorDb The floor of a null, dB (the kernel's `floor_db`).
+ */
+export declare function biquadMagnitudeDb(band: BiquadBand, freq: number, fs: number, floorDb: number): number;
+/**
+ * The summed magnitude of a band set at one frequency, dB (cascaded sections multiply, so dB add). The twin of
+ * omx_eq_magnitude_sum_db.
+ * @param floorDb The floor of each band's null, dB.
+ */
+export declare function magnitudeSumDb(bands: readonly BiquadBand[], f: number, fs: number, floorDb: number): number;

package/dist/eq.js

@@ -1,9 +1,240 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
-/** The twin of omx_eq_design.h omx_eq_octaves_q, moved verbatim from the console (its catalog package). */
-/** Bandwidth in octaves → Q (the cookbook relation). */
+/**
+ * The EQ twins: the Q relation and clamp, the section design and the magnitude a surface draws. Each is the
+ * TypeScript form of an omx_eq_design.h / omx_magnitude.h / omx_eq_instance.h kernel, pinned to it by
+ * test/agreement.test.mjs. A browser draws the curve with these; the engine runs the C.
+ */
+import { EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, LOWPASS_HANDOVER } from './definitions.js';
+import { linearToDbFloored } from './units.js';
+const clamp = (x, lo, hi) => (x < lo ? lo : x > hi ? hi : x);
+/** Bandwidth in octaves → Q (the cookbook relation). The twin of omx_eq_octaves_q. */
 export function octavesToQ(octaves) {
     const bw = Math.max(octaves, 0.05);
     const t = Math.pow(2, bw);
     return Math.sqrt(t) / (t - 1);
 }
+/**
+ * A band's Q clamped into the extent its shape allows: a notch may go ultra-narrow ({@link EQ_NOTCH_Q_RANGE}),
+ * every other shape keeps {@link EQ_Q_RANGE}. The twin of omx_eq_lv2_clamp_q, which clamps a float.
+ * @param type The band shape; only `'notch'` takes the notch range.
+ * @param q The asked Q.
+ */
+export function clampEqQFor(type, q) {
+    const r = type === 'notch' ? EQ_NOTCH_Q_RANGE : EQ_Q_RANGE;
+    return clamp(q, r.min, r.max);
+}
+/** How far a peaked low-pass hands its Nyquist target over: 0 at or below qHi, 1 at or above qPeak. */
+function lowpassNyquistHandover(q) {
+    const v = (q - LOWPASS_HANDOVER.qHi) / (LOWPASS_HANDOVER.qPeak - LOWPASS_HANDOVER.qHi);
+    return v <= 0 ? 0 : v >= 1 ? 1 : v;
+}
+/** How far a low-Q low-pass raises its Nyquist target across the hand-over: 0 at or above qHi, 1 at or below qLo. */
+function lowpassNyquistRaise(q) {
+    const u = (LOWPASS_HANDOVER.qHi - q) / (LOWPASS_HANDOVER.qHi - LOWPASS_HANDOVER.qLo);
+    return u <= 0 ? 0 : u >= 1 ? 1 : u;
+}
+/**
+ * The low-pass hand-over band for a Q, as fractions of Nyquist: the matched poles below the first, the bilinear
+ * pair from the second. The twin of omx_eq_lowpass_handover; the table is {@link LOWPASS_HANDOVER}.
+ */
+export function lowpassHandover(q) {
+    const h = LOWPASS_HANDOVER;
+    let u = (h.qHi - q) / (h.qHi - h.qLo);
+    u = u < 0 ? 0 : u > 1 ? 1 : u;
+    const lo = h.loAtHiQ + (h.loAtLoQ - h.loAtHiQ) * u;
+    let hi = h.hiAtHiQ + (h.hiAtLoQ - h.hiAtHiQ) * u;
+    hi += (h.hiAtPeakQ - h.hiAtHiQ) * lowpassNyquistHandover(q);
+    return [lo, hi];
+}
+/**
+ * One conjugate pair placed by the matched-Z map `z = exp(sT)`: the digital pair `1 + p1 z^-1 + p2 z^-2` of the
+ * analogue `s^2 + 2 zeta wn s + wn^2`, and `dc`, that polynomial at `z = 1` in a factored form that does not
+ * cancel for a low section. `wn` (radians per sample) is held at or below pi.
+ * @param wn The pair's centre, `2 pi f / fs`.
+ * @param zeta The damping, `1/(2Q)` for a plain resonator.
+ */
+export function matchedPair(wn, zeta) {
+    const w = wn > Math.PI ? Math.PI : wn;
+    const e = Math.exp(-zeta * w);
+    if (zeta < 1) {
+        const th = Math.sqrt(1 - zeta * zeta) * w;
+        const ec = e * Math.cos(th);
+        const es = e * Math.sin(th);
+        return { p1: -2 * ec, p2: e * e, dc: (1 - ec) * (1 - ec) + es * es };
+    }
+    // real roots; zeta - sqrt(zeta^2-1) written as 1/(zeta + sqrt(zeta^2-1)), which keeps its digits as Q -> 0
+    const sq = Math.sqrt(zeta * zeta - 1);
+    const z1 = Math.exp(-w / (zeta + sq));
+    const z2 = Math.exp(-w * (zeta + sq));
+    return { p1: -(z1 + z2), p2: z1 * z2, dc: (1 - z1) * (1 - z2) };
+}
+/**
+ * One section as omx_eq_design designs it: matched-Z peaking and shelves, a matched low-pass with its fitted
+ * numerator and Nyquist hand-over, a matched notch under the cookbook numerator, the cookbook high-pass and
+ * bandpass, and the first- and second-order allpasses. The centre is clamped to `[1, 0.999 Nyquist]` and a Q at
+ * or under 0 is taken as 1e-3; `gainDb` is read by the peaking and shelf kinds only.
+ * @param kind The section kind.
+ * @param freqHz Centre or corner, Hz.
+ * @param q Quality factor.
+ * @param gainDb Gain, dB.
+ * @param sampleRate Rate the section runs at, Hz.
+ */
+export function rbjSection(kind, freqHz, q, gainDb, sampleRate) {
+    const nyquist = sampleRate * 0.5;
+    const f0 = clamp(freqHz, 1, nyquist * 0.999);
+    const qq = q <= 0 ? 1e-3 : q;
+    const w0 = (2 * Math.PI * f0) / sampleRate;
+    const A = Math.pow(10, gainDb / 40);
+    switch (kind) {
+        case 'peaking': {
+            const p = matchedPair(w0, 1 / (2 * A * qq));
+            const z = matchedPair(w0, A / (2 * qq));
+            const k = p.dc / z.dc;
+            return { b0: k, b1: k * z.p1, b2: k * z.p2, a0: 1, a1: p.p1, a2: p.p2 };
+        }
+        case 'lowShelf': {
+            const sa = Math.sqrt(A);
+            const p = matchedPair(w0 / sa, 1 / (2 * qq));
+            const z = matchedPair(w0 * sa, 1 / (2 * qq));
+            const k = (A * A * p.dc) / z.dc;
+            return { b0: k, b1: k * z.p1, b2: k * z.p2, a0: 1, a1: p.p1, a2: p.p2 };
+        }
+        case 'highShelf': {
+            const sa = Math.sqrt(A);
+            const p = matchedPair(w0 * sa, 1 / (2 * qq));
+            const z = matchedPair(w0 / sa, 1 / (2 * qq));
+            const k = p.dc / z.dc;
+            return { b0: k, b1: k * z.p1, b2: k * z.p2, a0: 1, a1: p.p1, a2: p.p2 };
+        }
+        case 'highpass': {
+            const cw = Math.cos(w0);
+            const alpha = Math.sin(w0) / (2 * qq);
+            const a0 = 1 + alpha;
+            return { b0: (1 + cw) / 2 / a0, b1: -(1 + cw) / a0, b2: (1 + cw) / 2 / a0, a0: 1, a1: (-2 * cw) / a0, a2: (1 - alpha) / a0 };
+        }
+        case 'lowpass': {
+            const m = matchedPair(w0, 1 / (2 * qq));
+            const band = lowpassHandover(qq);
+            const r = f0 / nyquist;
+            const x = (r - band[0]) / (band[1] - band[0]);
+            const t = x <= 0 ? 0 : x >= 1 ? 1 : x * x * (3 - 2 * x);
+            const h = 2 * x - 1;
+            const v = h <= 0 ? 0 : h >= 1 ? 1 : h * h * (3 - 2 * h);
+            const p = { p1: m.p1, p2: m.p2, dc: m.dc };
+            if (t > 0) {
+                const cwh = Math.cos(w0);
+                const alpha = Math.sin(w0) / (2 * qq);
+                const a0 = 1 + alpha;
+                p.p1 = m.p1 + ((-2 * cwh) / a0 - m.p1) * t;
+                p.p2 = m.p2 + ((1 - alpha) / a0 - m.p2) * t;
+                p.dc = 1 + p.p1 + p.p2;
+            }
+            const keep = (1 - t * lowpassNyquistHandover(qq)) * (1 + v * lowpassNyquistRaise(qq));
+            if (keep === 0) {
+                const g = (1 + p.p1 + p.p2) / 4;
+                return { b0: g, b1: 2 * g, b2: g, a0: 1, a1: p.p1, a2: p.p2 };
+            }
+            // the prototype's |H|^2 at DC (1), at f0 (Q^2) and at Nyquist, and |D|^2 at the same three points
+            const xn = nyquist / f0;
+            const un = 1 - xn * xn;
+            const tPi = 1 / (un * un + (xn / qq) * (xn / qq));
+            const dPi = 1 - p.p1 + p.p2;
+            const cw = Math.cos(w0);
+            const dr = 1 + p.p1 * cw + p.p2 * Math.cos(2 * w0);
+            const di = -(p.p1 * Math.sin(w0) + p.p2 * Math.sin(2 * w0));
+            // |N|^2 = U - 4 V s + 16 W s^2 with s = sin^2(w/2), solved from the three points
+            const s0 = Math.sin(w0 / 2) * Math.sin(w0 / 2);
+            const U = p.dc * p.dc;
+            const r1 = tPi * dPi * dPi * keep - U;
+            const r2 = qq * qq * (dr * dr + di * di) - U;
+            const W = (r2 - s0 * r1) / (16 * s0 * (s0 - 1));
+            const n1 = Math.sqrt(U);
+            const nm = Math.sqrt(U + r1 > 0 ? U + r1 : 0);
+            const sum = (n1 + nm) / 2;
+            const b1 = (n1 - nm) / 2;
+            const disc = sum * sum - 4 * W;
+            const b0 = (sum + Math.sqrt(disc > 0 ? disc : 0)) / 2;
+            return { b0, b1, b2: sum - b0, a0: 1, a1: p.p1, a2: p.p2 };
+        }
+        case 'notch': {
+            const b1 = -2 * Math.cos(w0);
+            const p = matchedPair(w0, 1 / (2 * qq));
+            const sw2 = Math.sin(w0 / 2);
+            const k = p.dc / (4 * sw2 * sw2); // 4 sin^2(w0/2) is 2 + b1 without the cancellation
+            return { b0: k, b1: k * b1, b2: k, a0: 1, a1: p.p1, a2: p.p2 };
+        }
+        case 'bandpass': {
+            const cw = Math.cos(w0);
+            const alpha = Math.sin(w0) / (2 * qq);
+            const a0 = 1 + alpha;
+            return { b0: alpha / a0, b1: 0, b2: -alpha / a0, a0: 1, a1: (-2 * cw) / a0, a2: (1 - alpha) / a0 };
+        }
+        case 'allpass1': {
+            const t = Math.sin(w0) / (1 + Math.cos(w0));
+            const k = (t - 1) / (t + 1);
+            return { b0: k, b1: 1, b2: 0, a0: 1, a1: k, a2: 0 };
+        }
+        case 'allpass2': {
+            const K = Math.tan((Math.PI * f0) / sampleRate);
+            const norm = 1 / (1 + K / qq + K * K);
+            const a1 = 2 * (K * K - 1) * norm;
+            const a2 = (1 - K / qq + K * K) * norm;
+            return { b0: a2, b1: a1, b2: 1, a0: 1, a1, a2 };
+        }
+    }
+}
+/**
+ * The magnitude of one designed section at `freq`, dB, by the unit-circle arithmetic itself. A point at or above
+ * Nyquist, or a degenerate denominator, is 0 dB; a full null floors at `floorDb`.
+ * @param section The section.
+ * @param freq Probe frequency, Hz.
+ * @param fs Sample rate, Hz.
+ * @param floorDb The floor of a null, dB.
+ */
+export function sectionMagnitudeDb(section, freq, fs, floorDb) {
+    if (!(freq > 0) || !(fs > 0) || freq >= fs / 2)
+        return 0;
+    const { b0, b1, b2, a0, a1, a2 } = section;
+    const w = (2 * Math.PI * freq) / fs;
+    const cw = Math.cos(w);
+    const sw = Math.sin(w);
+    const cw2 = Math.cos(2 * w);
+    const sw2 = Math.sin(2 * w);
+    const num = Math.hypot(b0 + b1 * cw + b2 * cw2, -(b1 * sw + b2 * sw2));
+    const den = Math.hypot(a0 + a1 * cw + a2 * cw2, -(a1 * sw + a2 * sw2));
+    if (den === 0)
+        return 0;
+    return linearToDbFloored(num / den, floorDb);
+}
+const SHAPE_KIND = {
+    bell: 'peaking',
+    lowshelf: 'lowShelf',
+    highshelf: 'highShelf',
+    highpass: 'highpass',
+    lowpass: 'lowpass',
+    notch: 'notch',
+    allpass1: 'allpass1',
+    allpass2: 'allpass2',
+};
+/**
+ * One band's magnitude at `freq`, dB: {@link rbjSection} evaluated by {@link sectionMagnitudeDb}. The twin of
+ * omx_eq_band_magnitude_db.
+ * @param floorDb The floor of a null, dB (the kernel's `floor_db`).
+ */
+export function biquadMagnitudeDb(band, freq, fs, floorDb) {
+    if (!(freq > 0) || !(fs > 0) || freq >= fs / 2)
+        return 0;
+    return sectionMagnitudeDb(rbjSection(SHAPE_KIND[band.type], band.freq, band.q, band.gainDb, fs), freq, fs, floorDb);
+}
+/**
+ * The summed magnitude of a band set at one frequency, dB (cascaded sections multiply, so dB add). The twin of
+ * omx_eq_magnitude_sum_db.
+ * @param floorDb The floor of each band's null, dB.
+ */
+export function magnitudeSumDb(bands, f, fs, floorDb) {
+    let db = 0;
+    for (const b of bands)
+        db += biquadMagnitudeDb(b, f, fs, floorDb);
+    return db;
+}

package/dist/index.d.ts

@@ -4,5 +4,6 @@
  * agreement test in test/ that feeds both the same grid.
  */
 export { ANALYSIS_FLOOR_DB, dbToLinearGain, linearGainToDb, linearToDbFloored } from './units.js';
-export { octavesToQ } from './eq.js';
+export { biquadMagnitudeDb, clampEqQFor, lowpassHandover, magnitudeSumDb, matchedPair, octavesToQ, rbjSection, sectionMagnitudeDb, type BiquadBand, type BiquadKind, type BiquadSection, type BiquadType, } from './eq.js';
+export { EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, LOWPASS_HANDOVER, RTA_FFT_SIZE_MAX, RTA_TARGET_BIN_HZ } from './definitions.js';
 export { fftSizeForRate } from './rta.js';

package/dist/index.js

@@ -6,5 +6,6 @@
  * agreement test in test/ that feeds both the same grid.
  */
 export { ANALYSIS_FLOOR_DB, dbToLinearGain, linearGainToDb, linearToDbFloored } from './units.js';
-export { octavesToQ } from './eq.js';
+export { biquadMagnitudeDb, clampEqQFor, lowpassHandover, magnitudeSumDb, matchedPair, octavesToQ, rbjSection, sectionMagnitudeDb, } from './eq.js';
+export { EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, LOWPASS_HANDOVER, RTA_FFT_SIZE_MAX, RTA_TARGET_BIN_HZ } from './definitions.js';
 export { fftSizeForRate } from './rta.js';

package/oracle/ts-twin-oracle.c

@@ -0,0 +1,392 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/*
+ * The C side of the TypeScript-twin agreement tests (#1823).
+ *
+ * omx-dsp holds the law for a set of small kernels that the console also carries in TypeScript
+ * (each header tags its kernel `@twin <name>`). A twin cannot be bit-identical to its kernel: the
+ * kernel runs libm in double or float, the twin runs V8's math in double. So each twin is pinned
+ * by a test that feeds both the same inputs and compares the answers within a stated tolerance.
+ * This program is the kernel half. It reads requests on stdin, one per line,
+ *
+ *     <kernel> <number> <number> ...
+ *
+ * and answers each with one line, `ok <number> <number> ...` or `err <word>`. Numbers are decimal
+ * (JavaScript's own shortest round-trip form in, "%.17g" out), so no value is rounded on the way.
+ * Each kernel's argument layout is the comment above its handler. Float kernels are called with the
+ * inputs narrowed to float and answer the float widened back, exactly as the engine calls them.
+ *
+ * It links omx-dsp (ts-twin-oracle.mjs says which build), never a copy of any maths of its own: a number
+ * here that the library does not produce is a bug in this file.
+ */
+#include <math.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <omxdsp/analysis/omx_align_fit.h>
+#include <omxdsp/analysis/omx_hrp_correct.h>
+#include <omxdsp/analysis/omx_hrp_track.h>
+#include <omxdsp/analysis/omx_room.h>
+#include <omxdsp/analysis/omx_rta.h>
+#include <omxdsp/fx/omx_eq_instance.h>
+#include <omxdsp/mix/omx_pan_law.h>
+#include <omxdsp/omx_balance_law.h>
+#include <omxdsp/omx_contract.h>
+#include <omxdsp/omx_dyn.h>
+#include <omxdsp/omx_eq_design.h>
+#include <omxdsp/omx_magnitude.h>
+#include <omxdsp/omx_units.h>
+
+#define MAXV 4096
+#define MAXOUT 8192
+
+typedef int (*handler)(const double *in, int n, double *out);
+
+/* eq_design: kind freq q gain_db rate -> b0 b1 b2 a1 a2 */
+static int h_eq_design(const double *in, int n, double *out) {
+  if (n != 5) return -1;
+  omx_eq_design((enum omx_eq_kind)(int)in[0], in[1], in[2], in[3], in[4], out);
+  return 5;
+}
+
+/* eq_octaves_q: bw_oct -> q */
+static int h_eq_octaves_q(const double *in, int n, double *out) {
+  if (n != 1) return -1;
+  out[0] = omx_eq_octaves_q(in[0]);
+  return 1;
+}
+
+/* eq_band_is_identity: kind gain_db -> 0|1 */
+static int h_eq_band_is_identity(const double *in, int n, double *out) {
+  if (n != 2) return -1;
+  out[0] = omx_eq_band_is_identity((enum omx_eq_kind)(int)in[0], in[1]);
+  return 1;
+}
+
+/* eq_lv2_clamp_q: lv2_band_type q -> q (float) */
+static int h_eq_lv2_clamp_q(const double *in, int n, double *out) {
+  if (n != 2) return -1;
+  out[0] = omx_eq_lv2_clamp_q((int)in[0], (float)in[1]);
+  return 1;
+}
+
+/* eq_bank: eq_on rate nbands { kind freq gain q on }*nbands -> count { b0 b1 b2 a1 a2 enabled }*count */
+static int h_eq_bank(const double *in, int n, double *out) {
+  if (n < 3) return -1;
+  const int nb = (int)in[2];
+  if (nb < 0 || nb > 64 || n != 3 + 5 * nb) return -1;
+  struct omx_eq_band bands[64];
+  double coeffs[64][5];
+  uint8_t enabled[64];
+  for (int i = 0; i < nb; i++) {
+    const double *b = in + 3 + 5 * i;
+    bands[i].kind = (enum omx_eq_kind)(int)b[0];
+    bands[i].freq_hz = b[1];
+    bands[i].gain_db = b[2];
+    bands[i].q = b[3];
+    bands[i].on = (int)b[4];
+  }
+  const uint32_t cnt = omx_eq_bank_design((int)in[0], bands, (uint32_t)nb, in[1], coeffs, enabled);
+  out[0] = cnt;
+  for (uint32_t i = 0; i < cnt; i++) {
+    for (int j = 0; j < 5; j++) out[1 + 6 * i + j] = coeffs[i][j];
+    out[1 + 6 * i + 5] = enabled[i];
+  }
+  return 1 + 6 * (int)cnt;
+}
+
+/* eq_pass: hpf_on hpf_freq hpf_slope24 lpf_on lpf_freq lpf_slope24 rate -> count { b0 b1 b2 a1 a2 }*count */
+static int h_eq_pass(const double *in, int n, double *out) {
+  if (n != 7) return -1;
+  const struct omx_eq_pass hpf = {(int)in[0], in[1], (int)in[2]};
+  const struct omx_eq_pass lpf = {(int)in[3], in[4], (int)in[5]};
+  double coeffs[OMX_EQ_PASS_MAX_SECTIONS][5];
+  const uint32_t cnt = omx_eq_pass_design(&hpf, &lpf, in[6], coeffs);
+  out[0] = cnt;
+  for (uint32_t i = 0; i < cnt; i++)
+    for (int j = 0; j < 5; j++) out[1 + 5 * i + j] = coeffs[i][j];
+  return 1 + 5 * (int)cnt;
+}
+
+/* eq_band_magnitude_db: kind freq gain_db q at_hz rate floor_db -> dB */
+static int h_eq_band_magnitude_db(const double *in, int n, double *out) {
+  if (n != 7) return -1;
+  const struct omx_eq_band b = {(enum omx_eq_kind)(int)in[0], in[1], in[2], in[3], 1};
+  out[0] = omx_eq_band_magnitude_db(&b, in[4], in[5], in[6]);
+  return 1;
+}
+
+/* eq_magnitude_sum_db: at_hz rate floor_db nbands { kind freq gain q }*nbands -> dB */
+static int h_eq_magnitude_sum_db(const double *in, int n, double *out) {
+  if (n < 4) return -1;
+  const int nb = (int)in[3];
+  if (nb < 0 || nb > 64 || n != 4 + 4 * nb) return -1;
+  struct omx_eq_band bands[64];
+  for (int i = 0; i < nb; i++) {
+    const double *b = in + 4 + 4 * i;
+    bands[i].kind = (enum omx_eq_kind)(int)b[0];
+    bands[i].freq_hz = b[1];
+    bands[i].gain_db = b[2];
+    bands[i].q = b[3];
+    bands[i].on = 1;
+  }
+  out[0] = omx_eq_magnitude_sum_db(bands, (uint32_t)nb, in[0], in[1], in[2]);
+  return 1;
+}
+
+/* hrp_cut_db: excess_db amount max_cut_db -> cut_db (float) */
+static int h_hrp_cut_db(const double *in, int n, double *out) {
+  if (n != 3) return -1;
+  out[0] = omx_hrp_cut_db((float)in[0], (float)in[1], (float)in[2]);
+  return 1;
+}
+
+/* hrp_resonance_score: cut_db voice_confidence partial_confidence -> score (float) */
+static int h_hrp_resonance_score(const double *in, int n, double *out) {
+  if (n != 3) return -1;
+  out[0] = omx_hrp_resonance_score((float)in[0], (float)in[1], (float)in[2]);
+  return 1;
+}
+
+/* hrp_cents_between: a_hz b_hz -> cents (float) */
+static int h_hrp_cents_between(const double *in, int n, double *out) {
+  if (n != 2) return -1;
+  out[0] = omx_hrp_cents_between((float)in[0], (float)in[1]);
+  return 1;
+}
+
+/* pan_stereo: pan -> gain_l gain_r (float): the mono pan law over the stereo layout */
+static int h_pan_stereo(const double *in, int n, double *out) {
+  if (n != 1) return -1;
+  float l = 0.0f, r = 0.0f;
+  omx_pan_stereo((float)in[0], &l, &r);
+  out[0] = l;
+  out[1] = r;
+  return 2;
+}
+
+/* balance_law: pan -> gain_l gain_r (float): the stereo balance law */
+static int h_balance_law(const double *in, int n, double *out) {
+  if (n != 1) return -1;
+  float l = 0.0f, r = 0.0f;
+  omx_balance_law((float)in[0], &l, &r);
+  out[0] = l;
+  out[1] = r;
+  return 2;
+}
+
+/* lin_to_db: lin -> dB (float, floored at 1e-9) */
+static int h_lin_to_db(const double *in, int n, double *out) {
+  if (n != 1) return -1;
+  out[0] = omx_lin_to_db((float)in[0]);
+  return 1;
+}
+
+/* lin_to_db_d: lin floor_lin -> dB (double) */
+static int h_lin_to_db_d(const double *in, int n, double *out) {
+  if (n != 2) return -1;
+  out[0] = omx_lin_to_db_d(in[0], in[1]);
+  return 1;
+}
+
+/* db_to_lin: dB -> linear (float) */
+static int h_db_to_lin(const double *in, int n, double *out) {
+  if (n != 1) return -1;
+  out[0] = omx_db_to_lin((float)in[0]);
+  return 1;
+}
+
+/* eq_butterworth_qs: slope_24 -> sections q0 q1 (q1 is 0 for one section) */
+static int h_eq_butterworth_qs(const double *in, int n, double *out) {
+  if (n != 1) return -1;
+  double q[2] = {0.0, 0.0};
+  out[0] = omx_eq_butterworth_qs(in[0] != 0.0, q);
+  out[1] = q[0];
+  out[2] = q[1];
+  return 3;
+}
+
+/* dyn_oversample_factor: enabled ovs_mode attack_ms topology -> factor (attack narrowed to float, as the
+ * engine stores it) */
+static int h_dyn_oversample_factor(const double *in, int n, double *out) {
+  if (n != 4) return -1;
+  struct omx_dyn p;
+  memset(&p, 0, sizeof p);
+  p.enabled = in[0] != 0.0;
+  p.ovs_mode = (int)in[1];
+  p.attack_ms = (float)in[2];
+  p.topology = (int)in[3];
+  out[0] = omx_dyn_oversample_factor(&p);
+  return 1;
+}
+
+/* rta_fft_size_for: rate_hz -> window length */
+static int h_rta_fft_size_for(const double *in, int n, double *out) {
+  if (n != 1) return -1;
+  out[0] = omx_rta_fft_size_for((uint32_t)in[0]);
+  return 1;
+}
+
+/* align_correction: fit_delay_ms fit_invert applied_delay_ms applied_inverted travel_min travel_max
+ *                   -> delay_ms inverted clamped */
+static int h_align_correction(const double *in, int n, double *out) {
+  if (n != 6) return -1;
+  OmxAlignCorrection c;
+  omx_align_correction(in[0], (uint32_t)in[1], in[2], (uint32_t)in[3], in[4], in[5], &c);
+  out[0] = c.delay_ms;
+  out[1] = c.inverted;
+  out[2] = c.clamped;
+  return 3;
+}
+
+static int read_modes(const double *in, int count, OmxRoomMode *modes) {
+  for (int i = 0; i < count; i++) {
+    modes[i].hz = in[4 * i];
+    modes[i].positions = (uint32_t)in[4 * i + 1];
+    modes[i].q = in[4 * i + 2];
+    modes[i].above_median_db = in[4 * i + 3];
+  }
+  return 4 * count;
+}
+
+/* room_mode_eq_proposals: min_positions nmodes { hz positions q above_median_db }*nmodes
+ *                         -> count { hz gain_db q positions bounded requested_db }*count */
+static int h_room_mode_eq_proposals(const double *in, int n, double *out) {
+  if (n < 2) return -1;
+  const int nm = (int)in[1];
+  if (nm < 0 || nm > 64 || n != 2 + 4 * nm) return -1;
+  OmxRoomMode modes[64];
+  OmxRoomModeEqProposal props[64];
+  read_modes(in + 2, nm, modes);
+  uint32_t cnt = 0;
+  omx_room_mode_eq_proposals(modes, (uint32_t)nm, (uint32_t)in[0], props, 64u, &cnt);
+  out[0] = cnt;
+  for (uint32_t i = 0; i < cnt; i++) {
+    out[1 + 6 * i + 0] = props[i].hz;
+    out[1 + 6 * i + 1] = props[i].gain_db;
+    out[1 + 6 * i + 2] = props[i].q;
+    out[1 + 6 * i + 3] = props[i].positions;
+    out[1 + 6 * i + 4] = props[i].bounded;
+    out[1 + 6 * i + 5] = props[i].requested_db;
+  }
+  return 1 + 6 * (int)cnt;
+}
+
+/* room_mode_residual_db: target_hz nbins { hz }*nbins { magnitude_db }*nbins -> has_value value */
+static int h_room_mode_residual_db(const double *in, int n, double *out) {
+  if (n < 2) return -1;
+  const int nb = (int)in[1];
+  if (nb < 0 || nb > 1024 || n != 2 + 2 * nb) return -1;
+  static double scratch[1024];
+  double residual = 0.0;
+  const int has = omx_room_mode_residual_db(in + 2, in + 2 + nb, (uint32_t)nb, in[0], scratch, &residual);
+  out[0] = has;
+  out[1] = has ? residual : 0.0;
+  return 2;
+}
+
+/* room_mode_set_stable: tolerance_hz nbefore nafter { hz }*nbefore { hz }*nafter -> 0|1 */
+static int h_room_mode_set_stable(const double *in, int n, double *out) {
+  if (n < 3) return -1;
+  const int nb = (int)in[1], na = (int)in[2];
+  if (nb < 0 || na < 0 || nb > 64 || na > 64 || n != 3 + nb + na) return -1;
+  OmxRoomMode before[64], after[64];
+  unsigned char used[64];
+  for (int i = 0; i < nb; i++) before[i] = (OmxRoomMode){in[3 + i], 2u, 5.0, 6.0};
+  for (int i = 0; i < na; i++) after[i] = (OmxRoomMode){in[3 + nb + i], 2u, 5.0, 6.0};
+  out[0] = omx_room_mode_set_stable(before, (uint32_t)nb, after, (uint32_t)na, in[0], used);
+  return 1;
+}
+
+static const struct {
+  const char *name;
+  handler fn;
+} TABLE[] = {
+    {"eq_design", h_eq_design},
+    {"eq_octaves_q", h_eq_octaves_q},
+    {"eq_band_is_identity", h_eq_band_is_identity},
+    {"eq_lv2_clamp_q", h_eq_lv2_clamp_q},
+    {"eq_bank", h_eq_bank},
+    {"eq_pass", h_eq_pass},
+    {"eq_band_magnitude_db", h_eq_band_magnitude_db},
+    {"eq_magnitude_sum_db", h_eq_magnitude_sum_db},
+    {"hrp_cut_db", h_hrp_cut_db},
+    {"hrp_resonance_score", h_hrp_resonance_score},
+    {"hrp_cents_between", h_hrp_cents_between},
+    {"pan_stereo", h_pan_stereo},
+    {"balance_law", h_balance_law},
+    {"lin_to_db", h_lin_to_db},
+    {"lin_to_db_d", h_lin_to_db_d},
+    {"db_to_lin", h_db_to_lin},
+    {"rta_fft_size_for", h_rta_fft_size_for},
+    {"eq_butterworth_qs", h_eq_butterworth_qs},
+    {"dyn_oversample_factor", h_dyn_oversample_factor},
+    {"align_correction", h_align_correction},
+    {"room_mode_eq_proposals", h_room_mode_eq_proposals},
+    {"room_mode_residual_db", h_room_mode_residual_db},
+    {"room_mode_set_stable", h_room_mode_set_stable},
+};
+
+/* The kernels the table answers, for a test that asks "is the oracle really here". */
+static void list_kernels(void) {
+  for (size_t i = 0; i < sizeof TABLE / sizeof TABLE[0]; i++) printf("%s\n", TABLE[i].name);
+}
+
+/* The rates a rate-dependent twin is checked at: the contract's full oracle grid, as the library was built with it. */
+static void list_rates(void) {
+  static const float rates[OMX_ORACLE_FULL_RATES_COUNT] = OMX_ORACLE_FULL_RATES_INIT;
+  for (uint32_t i = 0; i < OMX_ORACLE_FULL_RATES_COUNT; i++) printf("%.17g\n", (double)rates[i]);
+}
+
+int main(int argc, char **argv) {
+  if (argc > 1 && strcmp(argv[1], "--list") == 0) {
+    list_kernels();
+    return 0;
+  }
+  if (argc > 1 && strcmp(argv[1], "--rates") == 0) {
+    list_rates();
+    return 0;
+  }
+  static char line[1 << 20];
+  static double in[MAXV], out[MAXOUT];
+  while (fgets(line, sizeof line, stdin)) {
+    char *save = NULL;
+    char *name = strtok_r(line, " \t\r\n", &save);
+    if (!name) continue;
+    int n = 0;
+    for (char *tok; (tok = strtok_r(NULL, " \t\r\n", &save)) != NULL;) {
+      if (n >= MAXV) {
+        n = -2;
+        break;
+      }
+      char *end = NULL;
+      in[n++] = strtod(tok, &end);
+      if (*end) {
+        n = -3;
+        break;
+      }
+    }
+    if (n < 0) {
+      printf("err bad-number\n");
+      continue;
+    }
+    handler fn = NULL;
+    for (size_t i = 0; i < sizeof TABLE / sizeof TABLE[0]; i++)
+      if (strcmp(TABLE[i].name, name) == 0) fn = TABLE[i].fn;
+    if (!fn) {
+      printf("err unknown-kernel\n");
+      continue;
+    }
+    const int k = fn(in, n, out);
+    if (k < 0) {
+      printf("err bad-arity\n");
+      continue;
+    }
+    printf("ok");
+    for (int i = 0; i < k; i++) printf(" %.17g", out[i]);
+    printf("\n");
+  }
+  return 0;
+}

package/oracle/ts-twin-oracle.d.mts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+export interface Tolerance {
+  /** Allowed relative gap, a fraction of the kernel's number. */
+  readonly rel?: number;
+  /** Allowed absolute gap. */
+  readonly abs?: number;
+}
+export declare const oraclePath: () => string;
+export declare const oracleKernels: () => string[];
+/** The contract's full oracle rate grid, as the library was built with it. */
+export declare const oracleRates: () => number[];
+/** The flags the oracle is built with and where its library came from. */
+export declare const linkage: () => { from: string; flags: string };
+/** One answer row per question row, in order. */
+export declare const oracle: (kernel: string, rows: readonly (readonly number[])[]) => number[][];
+/** '' when `twin` agrees with `kernel` inside `tol`, else a sentence saying how far off it is. */
+export declare const gap: (twin: number, kernel: number, tol: Tolerance) => string;
+export declare const compare: (
+  twin: readonly number[],
+  kernel: readonly number[],
+  tol: Tolerance,
+  label?: string,
+) => { failures: string[]; worst: number };
+export interface Asked {
+  readonly kernel: string;
+  readonly rows: readonly (readonly number[])[];
+  readonly answers: readonly (readonly number[])[];
+}
+export declare const ask: (kernel: string, rows: readonly (readonly number[])[]) => Asked;
+export declare const against: (
+  asked: Asked,
+  twin: (row: readonly number[]) => readonly number[],
+  tol: Tolerance,
+) => { rows: number; failures: string[]; worst: number };

package/oracle/ts-twin-oracle.mjs

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The kernel half of every agreement test: ts-twin-oracle.c answers a kernel by name for a grid of rows, one
+ * process per call. It links, in this order: the library OMXDSP_CFLAGS and OMXDSP_LIBS name (a consumer that
+ * resolves its own omx-dsp build sets both), this checkout's build/libomxdsp.a when `make lib` has built it (CI
+ * does), else the installed omx-dsp through pkg-config, and says which on stderr so a run never hides what it
+ * measured. Published in @openmixer/omx-dsp as `@openmixer/omx-dsp/oracle`, with the C source beside it.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SRC = join(HERE, 'ts-twin-oracle.c');
+const REPO = join(HERE, '..', '..');
+
+/** The compile and link flags: the caller's library first, the in-tree one second, the installed one third. */
+export const linkage = () => {
+  const { OMXDSP_CFLAGS: cflags, OMXDSP_LIBS: libs } = process.env;
+  if (cflags !== undefined || libs !== undefined) {
+    if (cflags === undefined || !libs) throw new Error('ts-twin-oracle: set both OMXDSP_CFLAGS and OMXDSP_LIBS, or neither');
+    return { from: `OMXDSP_LIBS ${libs}`, flags: `${cflags} -o @ '${SRC}' ${libs}` };
+  }
+  const archive = join(REPO, 'build', 'libomxdsp.a');
+  if (existsSync(archive) && existsSync(join(REPO, 'include', 'omxdsp'))) return { from: 'tree', flags: `-ffp-contract=off -I'${join(REPO, 'include')}' -o @ '${SRC}' '${archive}' -lm` };
+  const pc = execFileSync('pkg-config', ['--cflags', '--libs', 'omxdsp'], { encoding: 'utf8' }).trim();
+  return { from: `installed omx-dsp ${execFileSync('pkg-config', ['--modversion', 'omxdsp'], { encoding: 'utf8' }).trim()}`, flags: `-o @ '${SRC}' ${pc}` };
+};
+
+let built = '';
+export const oraclePath = () => {
+  if (built) return built;
+  const { from, flags } = linkage();
+  // an archive the flags name is part of the key, so a rebuilt library is never answered by an old binary
+  const stamp = (flags.match(/'?([^' ]+\.a)'?/g) ?? []).map((a) => a.replace(/'/g, '')).filter(existsSync).map((a) => `${a}:${statSync(a).size}:${statSync(a).mtimeMs}`).join(',');
+  const key = createHash('sha256').update(readFileSync(SRC)).update(flags).update(stamp).digest('hex').slice(0, 16);
+  const dir = join(tmpdir(), `omx-dsp-ts-oracle-${process.getuid?.() ?? 0}`);
+  mkdirSync(dir, { recursive: true });
+  const bin = join(dir, `oracle-${key}`);
+  if (!existsSync(bin)) {
+    const tmp = `${bin}.${process.pid}`;
+    execFileSync('sh', ['-c', `cc -Wall -Wextra -Werror -O2 ${flags.replace('-o @', `-o '${tmp}'`)}`], { stdio: ['ignore', 'inherit', 'inherit'] });
+    renameSync(tmp, bin);
+  }
+  process.stderr.write(`ts-twin-oracle: linked against the ${from}\n`);
+  built = bin;
+  return bin;
+};
+
+export const oracleKernels = () =>
+  execFileSync(oraclePath(), ['--list'], { encoding: 'utf8' }).split('\n').filter(Boolean);
+
+/** The rates a rate-dependent twin is checked at: the contract's full oracle grid the library was built with. */
+export const oracleRates = () =>
+  execFileSync(oraclePath(), ['--rates'], { encoding: 'utf8' }).split('\n').filter(Boolean).map(Number);
+
+const wire = (x) => {
+  if (Object.is(x, -0)) return '-0';
+  if (typeof x === 'boolean') return x ? '1' : '0';
+  if (Number.isNaN(x)) return 'nan';
+  if (x === Infinity) return 'inf';
+  if (x === -Infinity) return '-inf';
+  return String(x);
+};
+const unwire = (t) => {
+  const s = t.toLowerCase();
+  if (s === 'inf') return Infinity;
+  if (s === '-inf') return -Infinity;
+  if (s === 'nan' || s === '-nan') return NaN;
+  return Number(t);
+};
+
+/**
+ * Ask the C kernel `kernel` one question per row of `rows`; the answer rows come back in order.
+ * A refusal from the oracle (unknown kernel, wrong arity) throws: a silent empty answer would
+ * read as agreement with an empty twin.
+ */
+export const oracle = (kernel, rows) => {
+  if (rows.length === 0) throw new Error(`oracle(${kernel}): no rows — an empty grid proves nothing`);
+  const input = rows.map((r) => `${kernel} ${r.map(wire).join(' ')}\n`).join('');
+  const r = spawnSync(oraclePath(), [], { input, encoding: 'utf8', maxBuffer: 1 << 28 });
+  if (r.status !== 0) throw new Error(`oracle(${kernel}) exited ${r.status}: ${r.stderr}`);
+  const lines = r.stdout.split('\n').filter(Boolean);
+  if (lines.length !== rows.length) throw new Error(`oracle(${kernel}): ${rows.length} questions, ${lines.length} answers`);
+  return lines.map((line, i) => {
+    const [tag, ...rest] = line.split(' ');
+    if (tag !== 'ok') throw new Error(`oracle(${kernel}) row ${i} [${rows[i].join(' ')}]: ${line}`);
+    return rest.map(unwire);
+  });
+};
+
+/**
+ * The gap between a twin's number and the kernel's, as the test states its tolerance: a number
+ * agrees when it is within `abs` OR within `rel` of the kernel's (the larger of the two bounds), and
+ * non-finite answers agree only when they are the same non-finite value. Returns '' on agreement,
+ * else a sentence for the failure message.
+ */
+export const gap = (twin, kernel, { rel = 0, abs = 0 }) => {
+  if (Number.isNaN(twin) || Number.isNaN(kernel)) return Number.isNaN(twin) && Number.isNaN(kernel) ? '' : `twin ${twin}, kernel ${kernel}`;
+  if (!Number.isFinite(twin) || !Number.isFinite(kernel)) return twin === kernel ? '' : `twin ${twin}, kernel ${kernel}`;
+  const d = Math.abs(twin - kernel);
+  return d <= Math.max(abs, rel * Math.abs(kernel)) ? '' : `twin ${twin}, kernel ${kernel}, off by ${d} (allowed abs ${abs}, rel ${rel})`;
+};
+
+/**
+ * Compare two equal-length lists of numbers; returns the failures (an empty list is agreement) and
+ * the largest gap seen, so a test can print how close the tolerance sits to the truth.
+ */
+export const compare = (twin, kernel, tol, label = '') => {
+  if (twin.length !== kernel.length) return { failures: [`${label}: twin has ${twin.length} numbers, kernel ${kernel.length}`], worst: Infinity };
+  const failures = [];
+  let worst = 0;
+  for (let i = 0; i < twin.length; i++) {
+    const g = gap(twin[i], kernel[i], tol);
+    if (g) failures.push(`${label}[${i}]: ${g}`);
+    if (Number.isFinite(twin[i]) && Number.isFinite(kernel[i])) worst = Math.max(worst, Math.abs(twin[i] - kernel[i]));
+  }
+  return { failures, worst };
+};
+
+/** The kernel's answers to a grid, asked once so the twin and its sabotage arms read the same ones. */
+export const ask = (kernel, rows) => ({ kernel, rows, answers: oracle(kernel, rows) });
+
+/**
+ * Run `twin` (row -> list of numbers) over every row of an {@link ask} and compare with the kernel's
+ * answer inside `tol`. A twin that throws on a row is a failure of that row. Returns
+ * `{ rows, failures, worst }`: the row count, one sentence per disagreement and the largest finite gap.
+ */
+export const against = (asked, twin, tol) => {
+  const failures = [];
+  let worst = 0;
+  asked.rows.forEach((row, i) => {
+    let t;
+    try {
+      t = twin(row);
+    } catch (e) {
+      failures.push(`${asked.kernel}(${row.join(', ')}): the twin threw ${e}`);
+      return;
+    }
+    const c = compare(t, asked.answers[i], tol, `${asked.kernel}(${row.join(', ')})`);
+    failures.push(...c.failures);
+    worst = Math.max(worst, c.worst);
+  });
+  return { rows: asked.rows.length, failures, worst };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openmixer/omx-dsp",
-  "version": "0.28.0",
-  "description": "The TypeScript twins of omx-dsp kernels, each pinned to its C kernel by an agreement test",
+  "version": "0.29.0",
+  "description": "The TypeScript twins of omx-dsp kernels, each pinned to its C kernel by an agreement test, and the oracle that pins them",
   "type": "module",
   "license": "GPL-3.0-or-later",
   "author": "Pau Aliagas <linuxnow@gmail.com>",
@@ -16,11 +16,16 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./oracle": {
+      "types": "./oracle/ts-twin-oracle.d.mts",
+      "import": "./oracle/ts-twin-oracle.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist/",
-    "src/"
+    "src/",
+    "oracle/"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/definitions.ts

@@ -7,3 +7,21 @@ export const RTA_TARGET_BIN_HZ = 5.9;
 
 /** The largest RTA FFT the native ring holds — generated into `omx_contract_limits.h` as `OMX_RTA_FFT_SIZE_MAX`. @see data/kernels/rta.json */
 export const RTA_FFT_SIZE_MAX = 32768;
+
+/** Where the low-pass section hands its poles over from the matched pair to the prewarped bilinear pair, as fractions of Nyquist, and how that band moves with Q. At `qHi` (1/sqrt(2), the 12 dB Butterworth) the band runs from `loAtHiQ` to `hiAtHiQ`; at `qLo` (0.5412, the low-Q half of the 24 dB Butterworth) and below, from `loAtLoQ` to `hiAtLoQ`; between the two it moves linearly. Above `qHi` the prototype peaks, and the band's end moves down to `hiAtPeakQ` by `qPeak`, held above it. Below the band the low-pass is the matched design unchanged. @see data/kernels/eq.json */
+export const LOWPASS_HANDOVER = {
+  qHi: 0.7071067811865476,
+  qLo: 0.541196100146197,
+  qPeak: 0.9,
+  loAtHiQ: 0.6,
+  hiAtHiQ: 0.85,
+  loAtLoQ: 0.8,
+  hiAtLoQ: 0.9,
+  hiAtPeakQ: 0.8,
+} as const;
+
+/** The Q (resonance) extent of a parametric band. @see data/kernels/eq.json */
+export const EQ_Q_RANGE = { min: 0.3, max: 8 } as const;
+
+/** The Q extent of a NOTCH band. Wider than EQ_Q_RANGE on purpose (#116, operator decision): an ultra-narrow surgical cut is the notch shape's whole point — the FBS ring-out pool plants dbx-AFS-style ring killers at Q ≈ 116 (~1/80 octave), inaudible on program yet fatal to a single ringing frequency. Gain-carrying shapes stay bounded at EQ_Q_RANGE — a Q-116 bell is a resonator, not an EQ move. @see data/kernels/eq.json */
+export const EQ_NOTCH_Q_RANGE = { min: 0.3, max: 116 } as const;

package/src/eq.ts

@@ -1,10 +1,284 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
-/** The twin of omx_eq_design.h omx_eq_octaves_q, moved verbatim from the console (its catalog package). */
+/**
+ * The EQ twins: the Q relation and clamp, the section design and the magnitude a surface draws. Each is the
+ * TypeScript form of an omx_eq_design.h / omx_magnitude.h / omx_eq_instance.h kernel, pinned to it by
+ * test/agreement.test.mjs. A browser draws the curve with these; the engine runs the C.
+ */
+import { EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, LOWPASS_HANDOVER } from './definitions.js';
+import { linearToDbFloored } from './units.js';
 
-/** Bandwidth in octaves → Q (the cookbook relation). */
+const clamp = (x: number, lo: number, hi: number): number => (x < lo ? lo : x > hi ? hi : x);
+
+/** Bandwidth in octaves → Q (the cookbook relation). The twin of omx_eq_octaves_q. */
 export function octavesToQ(octaves: number): number {
   const bw = Math.max(octaves, 0.05);
   const t = Math.pow(2, bw);
   return Math.sqrt(t) / (t - 1);
 }
+
+/**
+ * A band's Q clamped into the extent its shape allows: a notch may go ultra-narrow ({@link EQ_NOTCH_Q_RANGE}),
+ * every other shape keeps {@link EQ_Q_RANGE}. The twin of omx_eq_lv2_clamp_q, which clamps a float.
+ * @param type The band shape; only `'notch'` takes the notch range.
+ * @param q The asked Q.
+ */
+export function clampEqQFor(type: string, q: number): number {
+  const r = type === 'notch' ? EQ_NOTCH_Q_RANGE : EQ_Q_RANGE;
+  return clamp(q, r.min, r.max);
+}
+
+/** The section kinds of omx_eq_design, by the twin's word (omx_eq_kind 0..8 in this order). */
+export type BiquadKind =
+  | 'peaking'
+  | 'lowShelf'
+  | 'highShelf'
+  | 'highpass'
+  | 'lowpass'
+  | 'notch'
+  | 'bandpass'
+  | 'allpass1'
+  | 'allpass2';
+
+/** One designed section, `a0` carried explicitly (every design here normalises, so it is 1). */
+export interface BiquadSection {
+  readonly b0: number;
+  readonly b1: number;
+  readonly b2: number;
+  readonly a0: number;
+  readonly a1: number;
+  readonly a2: number;
+}
+
+/** How far a peaked low-pass hands its Nyquist target over: 0 at or below qHi, 1 at or above qPeak. */
+function lowpassNyquistHandover(q: number): number {
+  const v = (q - LOWPASS_HANDOVER.qHi) / (LOWPASS_HANDOVER.qPeak - LOWPASS_HANDOVER.qHi);
+  return v <= 0 ? 0 : v >= 1 ? 1 : v;
+}
+
+/** How far a low-Q low-pass raises its Nyquist target across the hand-over: 0 at or above qHi, 1 at or below qLo. */
+function lowpassNyquistRaise(q: number): number {
+  const u = (LOWPASS_HANDOVER.qHi - q) / (LOWPASS_HANDOVER.qHi - LOWPASS_HANDOVER.qLo);
+  return u <= 0 ? 0 : u >= 1 ? 1 : u;
+}
+
+/**
+ * The low-pass hand-over band for a Q, as fractions of Nyquist: the matched poles below the first, the bilinear
+ * pair from the second. The twin of omx_eq_lowpass_handover; the table is {@link LOWPASS_HANDOVER}.
+ */
+export function lowpassHandover(q: number): readonly [number, number] {
+  const h = LOWPASS_HANDOVER;
+  let u = (h.qHi - q) / (h.qHi - h.qLo);
+  u = u < 0 ? 0 : u > 1 ? 1 : u;
+  const lo = h.loAtHiQ + (h.loAtLoQ - h.loAtHiQ) * u;
+  let hi = h.hiAtHiQ + (h.hiAtLoQ - h.hiAtHiQ) * u;
+  hi += (h.hiAtPeakQ - h.hiAtHiQ) * lowpassNyquistHandover(q);
+  return [lo, hi];
+}
+
+/**
+ * One conjugate pair placed by the matched-Z map `z = exp(sT)`: the digital pair `1 + p1 z^-1 + p2 z^-2` of the
+ * analogue `s^2 + 2 zeta wn s + wn^2`, and `dc`, that polynomial at `z = 1` in a factored form that does not
+ * cancel for a low section. `wn` (radians per sample) is held at or below pi.
+ * @param wn The pair's centre, `2 pi f / fs`.
+ * @param zeta The damping, `1/(2Q)` for a plain resonator.
+ */
+export function matchedPair(wn: number, zeta: number): { p1: number; p2: number; dc: number } {
+  const w = wn > Math.PI ? Math.PI : wn;
+  const e = Math.exp(-zeta * w);
+  if (zeta < 1) {
+    const th = Math.sqrt(1 - zeta * zeta) * w;
+    const ec = e * Math.cos(th);
+    const es = e * Math.sin(th);
+    return { p1: -2 * ec, p2: e * e, dc: (1 - ec) * (1 - ec) + es * es };
+  }
+  // real roots; zeta - sqrt(zeta^2-1) written as 1/(zeta + sqrt(zeta^2-1)), which keeps its digits as Q -> 0
+  const sq = Math.sqrt(zeta * zeta - 1);
+  const z1 = Math.exp(-w / (zeta + sq));
+  const z2 = Math.exp(-w * (zeta + sq));
+  return { p1: -(z1 + z2), p2: z1 * z2, dc: (1 - z1) * (1 - z2) };
+}
+
+/**
+ * One section as omx_eq_design designs it: matched-Z peaking and shelves, a matched low-pass with its fitted
+ * numerator and Nyquist hand-over, a matched notch under the cookbook numerator, the cookbook high-pass and
+ * bandpass, and the first- and second-order allpasses. The centre is clamped to `[1, 0.999 Nyquist]` and a Q at
+ * or under 0 is taken as 1e-3; `gainDb` is read by the peaking and shelf kinds only.
+ * @param kind The section kind.
+ * @param freqHz Centre or corner, Hz.
+ * @param q Quality factor.
+ * @param gainDb Gain, dB.
+ * @param sampleRate Rate the section runs at, Hz.
+ */
+export function rbjSection(kind: BiquadKind, freqHz: number, q: number, gainDb: number, sampleRate: number): BiquadSection {
+  const nyquist = sampleRate * 0.5;
+  const f0 = clamp(freqHz, 1, nyquist * 0.999);
+  const qq = q <= 0 ? 1e-3 : q;
+  const w0 = (2 * Math.PI * f0) / sampleRate;
+  const A = Math.pow(10, gainDb / 40);
+  switch (kind) {
+    case 'peaking': {
+      const p = matchedPair(w0, 1 / (2 * A * qq));
+      const z = matchedPair(w0, A / (2 * qq));
+      const k = p.dc / z.dc;
+      return { b0: k, b1: k * z.p1, b2: k * z.p2, a0: 1, a1: p.p1, a2: p.p2 };
+    }
+    case 'lowShelf': {
+      const sa = Math.sqrt(A);
+      const p = matchedPair(w0 / sa, 1 / (2 * qq));
+      const z = matchedPair(w0 * sa, 1 / (2 * qq));
+      const k = (A * A * p.dc) / z.dc;
+      return { b0: k, b1: k * z.p1, b2: k * z.p2, a0: 1, a1: p.p1, a2: p.p2 };
+    }
+    case 'highShelf': {
+      const sa = Math.sqrt(A);
+      const p = matchedPair(w0 * sa, 1 / (2 * qq));
+      const z = matchedPair(w0 / sa, 1 / (2 * qq));
+      const k = p.dc / z.dc;
+      return { b0: k, b1: k * z.p1, b2: k * z.p2, a0: 1, a1: p.p1, a2: p.p2 };
+    }
+    case 'highpass': {
+      const cw = Math.cos(w0);
+      const alpha = Math.sin(w0) / (2 * qq);
+      const a0 = 1 + alpha;
+      return { b0: (1 + cw) / 2 / a0, b1: -(1 + cw) / a0, b2: (1 + cw) / 2 / a0, a0: 1, a1: (-2 * cw) / a0, a2: (1 - alpha) / a0 };
+    }
+    case 'lowpass': {
+      const m = matchedPair(w0, 1 / (2 * qq));
+      const band = lowpassHandover(qq);
+      const r = f0 / nyquist;
+      const x = (r - band[0]) / (band[1] - band[0]);
+      const t = x <= 0 ? 0 : x >= 1 ? 1 : x * x * (3 - 2 * x);
+      const h = 2 * x - 1;
+      const v = h <= 0 ? 0 : h >= 1 ? 1 : h * h * (3 - 2 * h);
+      const p = { p1: m.p1, p2: m.p2, dc: m.dc };
+      if (t > 0) {
+        const cwh = Math.cos(w0);
+        const alpha = Math.sin(w0) / (2 * qq);
+        const a0 = 1 + alpha;
+        p.p1 = m.p1 + ((-2 * cwh) / a0 - m.p1) * t;
+        p.p2 = m.p2 + ((1 - alpha) / a0 - m.p2) * t;
+        p.dc = 1 + p.p1 + p.p2;
+      }
+      const keep = (1 - t * lowpassNyquistHandover(qq)) * (1 + v * lowpassNyquistRaise(qq));
+      if (keep === 0) {
+        const g = (1 + p.p1 + p.p2) / 4;
+        return { b0: g, b1: 2 * g, b2: g, a0: 1, a1: p.p1, a2: p.p2 };
+      }
+      // the prototype's |H|^2 at DC (1), at f0 (Q^2) and at Nyquist, and |D|^2 at the same three points
+      const xn = nyquist / f0;
+      const un = 1 - xn * xn;
+      const tPi = 1 / (un * un + (xn / qq) * (xn / qq));
+      const dPi = 1 - p.p1 + p.p2;
+      const cw = Math.cos(w0);
+      const dr = 1 + p.p1 * cw + p.p2 * Math.cos(2 * w0);
+      const di = -(p.p1 * Math.sin(w0) + p.p2 * Math.sin(2 * w0));
+      // |N|^2 = U - 4 V s + 16 W s^2 with s = sin^2(w/2), solved from the three points
+      const s0 = Math.sin(w0 / 2) * Math.sin(w0 / 2);
+      const U = p.dc * p.dc;
+      const r1 = tPi * dPi * dPi * keep - U;
+      const r2 = qq * qq * (dr * dr + di * di) - U;
+      const W = (r2 - s0 * r1) / (16 * s0 * (s0 - 1));
+      const n1 = Math.sqrt(U);
+      const nm = Math.sqrt(U + r1 > 0 ? U + r1 : 0);
+      const sum = (n1 + nm) / 2;
+      const b1 = (n1 - nm) / 2;
+      const disc = sum * sum - 4 * W;
+      const b0 = (sum + Math.sqrt(disc > 0 ? disc : 0)) / 2;
+      return { b0, b1, b2: sum - b0, a0: 1, a1: p.p1, a2: p.p2 };
+    }
+    case 'notch': {
+      const b1 = -2 * Math.cos(w0);
+      const p = matchedPair(w0, 1 / (2 * qq));
+      const sw2 = Math.sin(w0 / 2);
+      const k = p.dc / (4 * sw2 * sw2); // 4 sin^2(w0/2) is 2 + b1 without the cancellation
+      return { b0: k, b1: k * b1, b2: k, a0: 1, a1: p.p1, a2: p.p2 };
+    }
+    case 'bandpass': {
+      const cw = Math.cos(w0);
+      const alpha = Math.sin(w0) / (2 * qq);
+      const a0 = 1 + alpha;
+      return { b0: alpha / a0, b1: 0, b2: -alpha / a0, a0: 1, a1: (-2 * cw) / a0, a2: (1 - alpha) / a0 };
+    }
+    case 'allpass1': {
+      const t = Math.sin(w0) / (1 + Math.cos(w0));
+      const k = (t - 1) / (t + 1);
+      return { b0: k, b1: 1, b2: 0, a0: 1, a1: k, a2: 0 };
+    }
+    case 'allpass2': {
+      const K = Math.tan((Math.PI * f0) / sampleRate);
+      const norm = 1 / (1 + K / qq + K * K);
+      const a1 = 2 * (K * K - 1) * norm;
+      const a2 = (1 - K / qq + K * K) * norm;
+      return { b0: a2, b1: a1, b2: 1, a0: 1, a1, a2 };
+    }
+  }
+}
+
+/**
+ * The magnitude of one designed section at `freq`, dB, by the unit-circle arithmetic itself. A point at or above
+ * Nyquist, or a degenerate denominator, is 0 dB; a full null floors at `floorDb`.
+ * @param section The section.
+ * @param freq Probe frequency, Hz.
+ * @param fs Sample rate, Hz.
+ * @param floorDb The floor of a null, dB.
+ */
+export function sectionMagnitudeDb(section: BiquadSection, freq: number, fs: number, floorDb: number): number {
+  if (!(freq > 0) || !(fs > 0) || freq >= fs / 2) return 0;
+  const { b0, b1, b2, a0, a1, a2 } = section;
+  const w = (2 * Math.PI * freq) / fs;
+  const cw = Math.cos(w);
+  const sw = Math.sin(w);
+  const cw2 = Math.cos(2 * w);
+  const sw2 = Math.sin(2 * w);
+  const num = Math.hypot(b0 + b1 * cw + b2 * cw2, -(b1 * sw + b2 * sw2));
+  const den = Math.hypot(a0 + a1 * cw + a2 * cw2, -(a1 * sw + a2 * sw2));
+  if (den === 0) return 0;
+  return linearToDbFloored(num / den, floorDb);
+}
+
+/** The shapes a drawn band takes: the plugin and surface spelling. */
+export type BiquadType = 'bell' | 'lowshelf' | 'highshelf' | 'highpass' | 'lowpass' | 'notch' | 'allpass1' | 'allpass2';
+
+const SHAPE_KIND: Readonly<Record<BiquadType, BiquadKind>> = {
+  bell: 'peaking',
+  lowshelf: 'lowShelf',
+  highshelf: 'highShelf',
+  highpass: 'highpass',
+  lowpass: 'lowpass',
+  notch: 'notch',
+  allpass1: 'allpass1',
+  allpass2: 'allpass2',
+};
+
+/** One drawn band in engineering units. */
+export interface BiquadBand {
+  readonly type: BiquadType;
+  /** Centre or corner, Hz. */
+  readonly freq: number;
+  /** Gain, dB (bell and shelves only). */
+  readonly gainDb: number;
+  /** Quality factor. */
+  readonly q: number;
+}
+
+/**
+ * One band's magnitude at `freq`, dB: {@link rbjSection} evaluated by {@link sectionMagnitudeDb}. The twin of
+ * omx_eq_band_magnitude_db.
+ * @param floorDb The floor of a null, dB (the kernel's `floor_db`).
+ */
+export function biquadMagnitudeDb(band: BiquadBand, freq: number, fs: number, floorDb: number): number {
+  if (!(freq > 0) || !(fs > 0) || freq >= fs / 2) return 0;
+  return sectionMagnitudeDb(rbjSection(SHAPE_KIND[band.type], band.freq, band.q, band.gainDb, fs), freq, fs, floorDb);
+}
+
+/**
+ * The summed magnitude of a band set at one frequency, dB (cascaded sections multiply, so dB add). The twin of
+ * omx_eq_magnitude_sum_db.
+ * @param floorDb The floor of each band's null, dB.
+ */
+export function magnitudeSumDb(bands: readonly BiquadBand[], f: number, fs: number, floorDb: number): number {
+  let db = 0;
+  for (const b of bands) db += biquadMagnitudeDb(b, f, fs, floorDb);
+  return db;
+}

package/src/index.ts

@@ -6,5 +6,19 @@
  * agreement test in test/ that feeds both the same grid.
  */
 export { ANALYSIS_FLOOR_DB, dbToLinearGain, linearGainToDb, linearToDbFloored } from './units.js';
-export { octavesToQ } from './eq.js';
+export {
+  biquadMagnitudeDb,
+  clampEqQFor,
+  lowpassHandover,
+  magnitudeSumDb,
+  matchedPair,
+  octavesToQ,
+  rbjSection,
+  sectionMagnitudeDb,
+  type BiquadBand,
+  type BiquadKind,
+  type BiquadSection,
+  type BiquadType,
+} from './eq.js';
+export { EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, LOWPASS_HANDOVER, RTA_FFT_SIZE_MAX, RTA_TARGET_BIN_HZ } from './definitions.js';
 export { fftSizeForRate } from './rta.js';