@openmixer/omx-dsp 0.31.0 → 0.32.1

package/dist/fbs-place.js

@@ -0,0 +1,280 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * FbsPlace, the twin of omx_fbs_place.h (src/omx_fbs_place.c): the feedback corrector's placement, the console's
+ * FbsCorrector rules over a fixed set of slots. The C placement and this one read the same vector file
+ * (test/analysis/fixtures/fbs_place.vectors) in test/analysis/fbs_place.test.c and test/fbs-place.test.mjs, so the
+ * two are held to the same values: bit-equal where the rule is ordering or integer, within the file's stated
+ * tolerance where it is float (a gain stage's power).
+ *
+ * The rules are the header's, one method each, so a test can break one rule at a time. Time is the caller's, in
+ * ms; a release ramp's steps fire when the clock reaches them, before the tick at that time.
+ */
+import { CURVE_ORIGINS, CURVE_SHAPES, EQ_FREQ_RANGE, EQ_GAIN_RANGE, EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, FBS_BANDS_RANGE, FBS_COOLDOWN_RANGE, FBS_DEFAULT_COOLDOWN_SECONDS, FBS_DEFAULT_HOLD_SECONDS, FBS_DEFAULT_MAX_AUTO_BANDS, FBS_DEFAULT_MERGE_CENTS, FBS_DEFAULT_NOTCH_Q, FBS_HOLD_RANGE, FBS_LIFT_RAMP_MS, FBS_LIFT_RAMP_STEPS, FBS_MAX_CUT_DB, FBS_MERGE_RANGE, FBS_RECLAMP_BACKOFF_CAP, FBS_RECLAMP_DEEPEN_DB, FBS_RELEASE_DONE_DB, FBS_RELEASE_DWELL_MS, FBS_RELEASE_RATIO, FBS_RING_HZ_MAX, FBS_RING_HZ_MIN, FBS_RING_MEMORY_SLOTS, FBS_SAME_RING_HZ, FBS_SAME_RING_SHARE, } from './definitions.js';
+/** The console's FbsAction words, in OmxFbsAction's order. */
+export const FBS_ACTIONS = ['notched', 'lifted', 'pool-full', 're-armed', 'easing', 'rejected-edge'];
+/** The hold that never releases. */
+export const FBS_HOLD_NEVER = 'never';
+/** The CURVE_ORIGINS wire words, by index. */
+export const ORIGIN_WORDS = CURVE_ORIGINS.map((id) => id.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`));
+/** The CURVE_SHAPES words, by index (the unshaped band is `-`). */
+export const SHAPE_WORDS = CURVE_SHAPES.map((id) => (id === 'unshaped' ? '-' : id));
+const origin = (word) => ORIGIN_WORDS.indexOf(word);
+const shape = (word) => SHAPE_WORDS.indexOf(word);
+export const ORIGIN = { user: origin('user'), fbsFixed: origin('fbs-fixed'), fbsLive: origin('fbs-live') };
+export const SHAPE = { off: shape('off'), bell: shape('bell'), notch: shape('notch') };
+/** Slots one placement holds: the band cap's ceiling. */
+export const FBS_PLACE_SLOTS = FBS_BANDS_RANGE.max;
+const freeSlot = () => ({
+    freqHz: 0, gainDb: 0, q: 0, on: false, origin: ORIGIN.user, shape: SHAPE.off, seq: 0,
+    live: false, plantedDb: 0, lastRingMs: 0, stage: 0, dwellStartMs: null, reclamps: 0, ramp: null,
+});
+/** `n < lo ? lo : n > hi ? hi : n`: core's clamp, a NaN passing through. */
+const clamp = (n, lo, hi) => (n < lo ? lo : n > hi ? hi : n);
+/** The gain a band of `origin` may hold: fbs-* in [FBS_MAX_CUT_DB, 0] (NaN reads 0), every other origin in
+ * EQ_GAIN_RANGE (NaN stays NaN) — the strip store's arm. */
+export function fbsGainCap(originIndex, db) {
+    if (originIndex === ORIGIN.fbsFixed || originIndex === ORIGIN.fbsLive) {
+        if (Number.isNaN(db))
+            return 0;
+        return Math.min(0, Math.max(FBS_MAX_CUT_DB, db));
+    }
+    return clamp(db, EQ_GAIN_RANGE.min, EQ_GAIN_RANGE.max);
+}
+/** Two readings are the same ringing frequency: within FBS_SAME_RING_HZ or FBS_SAME_RING_SHARE of the higher. */
+export function sameRingFreq(aHz, bHz) {
+    return Math.abs(aHz - bHz) <= Math.max(FBS_SAME_RING_HZ, FBS_SAME_RING_SHARE * Math.max(aHz, bHz));
+}
+/** omx_hrp_cents_between in float: `fabsf(1200 * log2f(a / b))`, 1e9 when either is not positive. */
+export function fbsCents(aHz, bHz) {
+    const a = Math.fround(aHz);
+    const b = Math.fround(bHz);
+    if (!(a > 0) || !(b > 0))
+        return Math.fround(1e9);
+    return Math.abs(Math.fround(1200 * Math.fround(Math.log2(Math.fround(a / b)))));
+}
+/** Math.round's half-up rounding. */
+const round = (x) => Math.round(x);
+/** One corrector's placement: the console's FbsCorrector rules over fixed slots. */
+export class FbsPlace {
+    pool;
+    holdS = FBS_DEFAULT_HOLD_SECONDS;
+    maxBands = FBS_DEFAULT_MAX_AUTO_BANDS;
+    notchQ = FBS_DEFAULT_NOTCH_Q;
+    mergeCents = FBS_DEFAULT_MERGE_CENTS;
+    cooldownS = FBS_DEFAULT_COOLDOWN_SECONDS;
+    nowMs = 0;
+    memoryDropped = 0;
+    slots = Array.from({ length: FBS_PLACE_SLOTS }, freeSlot);
+    memory = [];
+    seq = 0;
+    timerSeq = 0;
+    log = [];
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /** The arming values, each clamped as the console clamps it. */
+    set(holdS, maxBands, notchQ, mergeCents, cooldownS) {
+        this.holdS = holdS === FBS_HOLD_NEVER ? FBS_HOLD_NEVER : Number.isFinite(holdS) ? clamp(holdS, FBS_HOLD_RANGE.min, FBS_HOLD_RANGE.max) : FBS_DEFAULT_HOLD_SECONDS;
+        this.maxBands = Number.isFinite(maxBands) ? clamp(round(maxBands), FBS_BANDS_RANGE.min, FBS_BANDS_RANGE.max) : FBS_DEFAULT_MAX_AUTO_BANDS;
+        this.notchQ = Number.isFinite(notchQ) ? clamp(notchQ, EQ_NOTCH_Q_RANGE.min, EQ_NOTCH_Q_RANGE.max) : FBS_DEFAULT_NOTCH_Q;
+        this.mergeCents = Number.isFinite(mergeCents) ? clamp(round(mergeCents), FBS_MERGE_RANGE.min, FBS_MERGE_RANGE.max) : FBS_DEFAULT_MERGE_CENTS;
+        this.cooldownS = Number.isFinite(cooldownS) ? clamp(round(cooldownS), FBS_COOLDOWN_RANGE.min, FBS_COOLDOWN_RANGE.max) : FBS_DEFAULT_COOLDOWN_SECONDS;
+    }
+    /** The bands planted, fixed and live together. */
+    count() {
+        return this.slots.filter((s) => s.origin !== ORIGIN.user).length;
+    }
+    /** Slot k's six report words. */
+    report(k) {
+        const s = this.slots[k];
+        if (!s || s.origin === ORIGIN.user)
+            return { freqHz: 0, depthDb: 0, q: 0, on: 0, origin: ORIGIN.user, shape: SHAPE.off };
+        return { freqHz: s.freqHz, depthDb: s.gainDb, q: s.q, on: s.on ? 1 : 0, origin: s.origin, shape: s.shape };
+    }
+    /** The ramp steps due by `nowMs`, earliest first, ties in the order the ramps began. */
+    advance(nowMs) {
+        for (;;) {
+            let next = -1;
+            for (let k = 0; k < this.slots.length; k++) {
+                const r = this.slots[k].ramp;
+                if (!r || r.dueMs > nowMs)
+                    continue;
+                const best = next < 0 ? null : this.slots[next].ramp;
+                if (!best || r.dueMs < best.dueMs || (r.dueMs === best.dueMs && r.seq < best.seq))
+                    next = k;
+            }
+            if (next < 0)
+                break;
+            this.nowMs = this.slots[next].ramp.dueMs;
+            this.rampStep(next);
+        }
+        if (nowMs > this.nowMs)
+            this.nowMs = nowMs;
+    }
+    /** One detector tick: the ramp steps due, a band per newly confirmed ring, then the clean holds. */
+    tick(nowMs, snapshotHz, confirmed) {
+        this.advance(nowMs);
+        for (const c of confirmed)
+            this.correct(c);
+        this.holdSweep(snapshotHz);
+    }
+    // ---- the rules, one method each ----------------------------------------------------------------------------
+    /** One find or another: the same-ring window, or the merge radius in cents (band first, find second). */
+    sameRegion(bandHz, findHz) {
+        return sameRingFreq(bandHz, findHz) || fbsCents(bandHz, findHz) <= this.mergeCents;
+    }
+    /** The pool a find goes to. */
+    poolOfFind() {
+        return this.pool;
+    }
+    /** The gain cap the placement writes through. */
+    capGain(originIndex, db) {
+        return fbsGainCap(originIndex, db);
+    }
+    /** The stage a release eases to after `stage`. */
+    nextStage(stage) {
+        return stage + 1;
+    }
+    /** Free slot k: it reports free and no other slot moves. */
+    release(k) {
+        this.slots[k] = freeSlot();
+    }
+    emit(action, freqHz, slot) {
+        this.log.push({ action, freqHz, slot });
+    }
+    /** Occupied slots in plant order: the console's band order. */
+    bySeq() {
+        return this.slots.map((s, k) => ({ s, k })).filter(({ s }) => s.origin !== ORIGIN.user).sort((a, b) => a.s.seq - b.s.seq).map(({ k }) => k);
+    }
+    correct(c) {
+        if (!(c.freqHz >= FBS_RING_HZ_MIN && c.freqHz <= FBS_RING_HZ_MAX)) {
+            this.emit('rejected-edge', c.freqHz, -1);
+            return;
+        }
+        const existing = this.bySeq().find((k) => this.sameRegion(this.slots[k].freqHz, c.freqHz));
+        if (existing !== undefined) {
+            const s = this.slots[existing];
+            if (s.live) {
+                s.lastRingMs = this.nowMs;
+                if (s.ramp !== null || s.stage > 0)
+                    this.reArm(existing);
+            }
+            return;
+        }
+        if (this.count() >= this.maxBands) {
+            this.emit('pool-full', c.freqHz, -1);
+            return;
+        }
+        const k = this.slots.findIndex((s) => s.origin === ORIGIN.user);
+        if (k < 0)
+            return;
+        const fixed = this.poolOfFind() === 'fixed';
+        const o = fixed ? ORIGIN.fbsFixed : ORIGIN.fbsLive;
+        const s = this.slots[k];
+        s.freqHz = clamp(c.freqHz, EQ_FREQ_RANGE.min, EQ_FREQ_RANGE.max);
+        s.shape = fixed ? SHAPE.notch : SHAPE.bell;
+        s.gainDb = this.capGain(o, fixed ? 0 : c.depthDb);
+        s.q = fixed ? clamp(this.notchQ, EQ_NOTCH_Q_RANGE.min, EQ_NOTCH_Q_RANGE.max) : clamp(this.notchQ, EQ_Q_RANGE.min, EQ_Q_RANGE.max);
+        s.on = true;
+        s.origin = o;
+        s.seq = ++this.seq;
+        s.live = !fixed;
+        s.plantedDb = s.gainDb;
+        s.lastRingMs = this.nowMs;
+        s.stage = 0;
+        s.dwellStartMs = null;
+        s.ramp = null;
+        s.reclamps = fixed ? 0 : this.takeMemory(s.freqHz);
+        this.emit('notched', c.freqHz, k);
+    }
+    holdSweep(snapshotHz) {
+        for (const k of this.bySeq()) {
+            const s = this.slots[k];
+            if (!s.live)
+                continue;
+            if (snapshotHz.some((hz) => sameRingFreq(hz, s.freqHz))) {
+                s.lastRingMs = this.nowMs;
+                if (s.ramp !== null || s.stage > 0)
+                    this.reArm(k);
+                continue;
+            }
+            if (s.ramp !== null)
+                continue;
+            if (this.holdS === FBS_HOLD_NEVER)
+                continue;
+            if (s.stage === 0) {
+                const holdMs = this.holdS * 1000 * 2 ** Math.min(s.reclamps, FBS_RECLAMP_BACKOFF_CAP);
+                if (this.nowMs - s.lastRingMs >= holdMs)
+                    this.beginStage(k, this.nextStage(0));
+            }
+            else if (s.dwellStartMs !== null && this.nowMs - s.dwellStartMs >= FBS_RELEASE_DWELL_MS) {
+                this.beginStage(k, this.nextStage(s.stage));
+            }
+        }
+    }
+    reArm(k) {
+        const s = this.slots[k];
+        s.ramp = null;
+        s.stage = 0;
+        s.dwellStartMs = null;
+        if (s.gainDb === s.plantedDb)
+            return;
+        s.reclamps += 1;
+        s.plantedDb = Math.max(FBS_MAX_CUT_DB, s.plantedDb - FBS_RECLAMP_DEEPEN_DB);
+        s.gainDb = this.capGain(s.origin, s.plantedDb);
+        this.emit('re-armed', s.freqHz, k);
+    }
+    beginStage(k, stage) {
+        const s = this.slots[k];
+        s.dwellStartMs = null;
+        s.ramp = { step: 0, stage, fromDb: s.gainDb, toDb: s.plantedDb * FBS_RELEASE_RATIO ** stage, dueMs: this.nowMs + FBS_LIFT_RAMP_MS / FBS_LIFT_RAMP_STEPS, seq: ++this.timerSeq };
+    }
+    rampStep(k) {
+        const s = this.slots[k];
+        const r = s.ramp;
+        r.step++;
+        if (r.step < FBS_LIFT_RAMP_STEPS) {
+            s.gainDb = this.capGain(s.origin, r.fromDb + (r.toDb - r.fromDb) * (r.step / FBS_LIFT_RAMP_STEPS));
+            r.dueMs += FBS_LIFT_RAMP_MS / FBS_LIFT_RAMP_STEPS;
+            return;
+        }
+        s.ramp = null;
+        if (Math.abs(r.toDb) < FBS_RELEASE_DONE_DB) {
+            if (s.reclamps > 0)
+                this.remember(s.freqHz, s.reclamps);
+            const hz = s.freqHz;
+            this.release(k);
+            this.emit('lifted', hz, k);
+            return;
+        }
+        s.gainDb = this.capGain(s.origin, r.toDb);
+        s.stage = r.stage;
+        s.dwellStartMs = this.nowMs;
+        this.emit('easing', s.freqHz, k);
+    }
+    remember(freqHz, reclamps) {
+        if (this.memory.length >= FBS_RING_MEMORY_SLOTS) {
+            this.memory.shift();
+            this.memoryDropped++;
+        }
+        this.memory.push({ freqHz, reclamps, releasedMs: this.nowMs });
+    }
+    takeMemory(freqHz) {
+        if (this.cooldownS <= 0)
+            return 0;
+        const cutoff = this.nowMs - this.cooldownS * 1000;
+        for (let i = this.memory.length - 1; i >= 0; i--) {
+            const m = this.memory[i];
+            if (m.releasedMs < cutoff) {
+                this.memory.splice(i, 1);
+                continue;
+            }
+            if (this.sameRegion(m.freqHz, freqHz)) {
+                this.memory.splice(i, 1);
+                return m.reclamps;
+            }
+        }
+        return 0;
+    }
+}

package/dist/index.d.ts

@@ -5,7 +5,10 @@
  */
 export { ANALYSIS_FLOOR_DB, dbToLinearGain, linearGainToDb, linearToDbFloored } from './units.js';
 export { biquadMagnitudeDb, clampEqQFor, lowpassHandover, magnitudeSumDb, matchedPair, octavesToQ, rbjSection, sectionMagnitudeDb, type BiquadBand, type BiquadKind, type BiquadSection, type BiquadType, } from './eq.js';
-export { COMP_KNEE_DB_RANGE, COMP_RATIO_RANGE, CURVE_CODES, CURVE_DISPLAYS, CURVE_EXTENTS, CURVE_FAMILIES, CURVE_POINTS_MAX, CURVE_ROLES, CURVE_SHAPES, CURVE_UNITS, EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, GATE_RANGE_DB_RANGE, GATE_RATIO_RANGE, LIN_TO_DB_FLOOR, LOWPASS_HANDOVER, RTA_FFT_SIZE_MAX, RTA_TARGET_BIN_HZ, } from './definitions.js';
+export { COMP_KNEE_DB_RANGE, COMP_RATIO_RANGE, CURVE_CODES, CURVE_DISPLAYS, CURVE_EXTENTS, CURVE_FAMILIES, CURVE_POINTS_MAX, CURVE_ORIGINS, CURVE_ROLES, CURVE_SHAPES, CURVE_UNITS, EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, GATE_RANGE_DB_RANGE, GATE_RATIO_RANGE, LIN_TO_DB_FLOOR, LOWPASS_HANDOVER, METER_DECIMATION, METER_KINDS, METER_MEASUREMENTS, METER_UNITS, METER_UNITS_LABELS, METER_VIEW, RTA_FFT_SIZE_MAX, RTA_TARGET_BIN_HZ, } from './definitions.js';
 export { fftSizeForRate } from './rta.js';
 export { gaincompDb, gaincompDbShifted, gateKnee, type GaincompMode, type GaincompParams } from './gaincomp.js';
-export { CURVE_WORDS, butterworthQs, curvePoints, type CurveAnswer, type CurveCode, type CurvePoint, type CurveRequest, type CurveTerm, } from './curve.js';
+export { CURVE_WORDS, butterworthQs, curvePoints, type CurveAnswer, type CurveCode, type CurveMark, type CurvePoint, type CurveRequest, type CurveTerm, } from './curve.js';
+export { FBS_ACTIONS, FBS_HOLD_NEVER, FBS_PLACE_SLOTS, FbsPlace, ORIGIN, ORIGIN_WORDS, SHAPE, SHAPE_WORDS, fbsCents, fbsGainCap, sameRingFreq, type BandReport, type FbsAction, type FbsEvent, type FbsFind, type FbsPool, } from './fbs-place.js';
+export { EQ_GAIN_RANGE, FBS_MAX_CUT_DB } from './definitions.js';
+export { METER_GR_EMPTY, METER_GR_HOLD_MS, METER_MARKER_EMPTY, METER_WORDS, meterBarStep, meterClip, meterDecimate, meterFill, meterFillDb, meterGrStep, meterGrView, meterMarker, meterStep, meterUnitOf, type MeterGr, type MeterKind, type MeterMarker, type MeterMeasurement, type MeterUnit, } from './meter.js';

package/dist/index.js

@@ -7,7 +7,10 @@
  */
 export { ANALYSIS_FLOOR_DB, dbToLinearGain, linearGainToDb, linearToDbFloored } from './units.js';
 export { biquadMagnitudeDb, clampEqQFor, lowpassHandover, magnitudeSumDb, matchedPair, octavesToQ, rbjSection, sectionMagnitudeDb, } from './eq.js';
-export { COMP_KNEE_DB_RANGE, COMP_RATIO_RANGE, CURVE_CODES, CURVE_DISPLAYS, CURVE_EXTENTS, CURVE_FAMILIES, CURVE_POINTS_MAX, CURVE_ROLES, CURVE_SHAPES, CURVE_UNITS, EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, GATE_RANGE_DB_RANGE, GATE_RATIO_RANGE, LIN_TO_DB_FLOOR, LOWPASS_HANDOVER, RTA_FFT_SIZE_MAX, RTA_TARGET_BIN_HZ, } from './definitions.js';
+export { COMP_KNEE_DB_RANGE, COMP_RATIO_RANGE, CURVE_CODES, CURVE_DISPLAYS, CURVE_EXTENTS, CURVE_FAMILIES, CURVE_POINTS_MAX, CURVE_ORIGINS, CURVE_ROLES, CURVE_SHAPES, CURVE_UNITS, EQ_NOTCH_Q_RANGE, EQ_Q_RANGE, GATE_RANGE_DB_RANGE, GATE_RATIO_RANGE, LIN_TO_DB_FLOOR, LOWPASS_HANDOVER, METER_DECIMATION, METER_KINDS, METER_MEASUREMENTS, METER_UNITS, METER_UNITS_LABELS, METER_VIEW, RTA_FFT_SIZE_MAX, RTA_TARGET_BIN_HZ, } from './definitions.js';
 export { fftSizeForRate } from './rta.js';
 export { gaincompDb, gaincompDbShifted, gateKnee } from './gaincomp.js';
 export { CURVE_WORDS, butterworthQs, curvePoints, } from './curve.js';
+export { FBS_ACTIONS, FBS_HOLD_NEVER, FBS_PLACE_SLOTS, FbsPlace, ORIGIN, ORIGIN_WORDS, SHAPE, SHAPE_WORDS, fbsCents, fbsGainCap, sameRingFreq, } from './fbs-place.js';
+export { EQ_GAIN_RANGE, FBS_MAX_CUT_DB } from './definitions.js';
+export { METER_GR_EMPTY, METER_GR_HOLD_MS, METER_MARKER_EMPTY, METER_WORDS, meterBarStep, meterClip, meterDecimate, meterFill, meterFillDb, meterGrStep, meterGrView, meterMarker, meterStep, meterUnitOf, } from './meter.js';

package/dist/meter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The meter view law, the twin of mix/omx_meter_view.h: how a measured value is drawn, the same on every surface.
+ * The fill of a dB scale from the floor to 0 dBFS, the peak marker that takes a louder value at once and falls by
+ * elapsed time (the same seconds give the same fall at any draw rate, and it falls on silence), the clip word that
+ * stays lit until cleared, the stepped count of an LED ladder with its hysteresis (a bar has no release), the
+ * gain-reduction reading recovered by the time elapsed at the reader's tick (the twin of omx_meter_gr_step), and what a
+ * decimating subscriber keeps. The numbers are METER_VIEW, declared in data/primitives/meter.json. Pinned by
+ * test/meter.test.mjs: against the kernel through the oracle at the nine oracle rates, and against
+ * vectors/meter-view.json, the file every copy of the law reads.
+ */
+import { METER_KINDS, METER_MEASUREMENTS, METER_UNITS } from './definitions.js';
+/** The wire words of the meter sets, in value order: `gain-reduction`, `true-peak`, `lufs-m`…; units as labelled. */
+export declare const METER_WORDS: {
+    readonly kinds: string[];
+    readonly measurements: string[];
+    readonly units: readonly ["dBFS", "dBTP", "LUFS", "LU", "dB"];
+};
+/** A meter's kind, as METER_KINDS spells it. */
+export type MeterKind = (typeof METER_KINDS)[number];
+/** The fill of a dB level, linear in dB from `floorDb` (0) to 0 dBFS (1); NaN and -Infinity read 0. Twin of omx_meter_view_fill_db. */
+export declare function meterFillDb(db: number, floorDb?: number): number;
+/** The fill of a linear peak (1 is 0 dBFS) on the same dB scale. Twin of omx_meter_view_fill. */
+export declare function meterFill(level: number, floorDb?: number): number;
+/** One meter's peak marker between draw ticks, the state of struct omx_meter_view. */
+export interface MeterMarker {
+    /** The fill the marker last took. */
+    readonly peak: number;
+    /** Seconds of draw ticks since it took it. */
+    readonly elapsedS: number;
+    /** The live fill of the last tick. */
+    readonly live: number;
+    /** The marker drawn at the last tick. */
+    readonly marker: number;
+}
+/** A fresh marker: empty. */
+export declare const METER_MARKER_EMPTY: MeterMarker;
+/**
+ * One draw tick of the peak marker: a fill at or above it is taken at once; below it the marker falls
+ * `fallDbPerSecond` for each second elapsed since it took its value, never under the live fill. `dtS` is the time
+ * since the last tick (negative or NaN counts as 0). Twin of omx_meter_view_step.
+ */
+export declare function meterMarker(prev: MeterMarker | undefined, fill: number, dtS: number, fallDbPerSecond?: number, floorDb?: number): MeterMarker;
+/** The clip word for one tick: lit by a clip, and lit until the surface clears it (sets it false). Twin of omx_meter_view_clip. */
+export declare function meterClip(lit: boolean, clip: boolean): boolean;
+/**
+ * A stepped display's count (an LED ladder of `steps` segments) with hysteresis against the count it showed last: it
+ * holds while the unrounded value stays within `0.5 + hysteresis` steps of it. `prevStep` undefined (or negative) is a
+ * fresh or reset strip: plain rounding. Twin of omx_meter_view_ladder.
+ */
+export declare function meterStep(prevStep: number | undefined, fill: number, steps: number, hysteresis?: number): number;
+/** A stepped BAR for one tick: a linear peak to its fill, then its count against the last one. No release. Twin of omx_meter_view_bar_step. */
+export declare function meterBarStep(prevStep: number | undefined, level: number, steps: number, hysteresis?: number): number;
+/** What a decimating subscriber keeps of two frames (METER_DECIMATION): a level the peak, a gain reduction the deepest; a NaN frame is never kept. Twin of omx_meter_view_decimate. */
+export declare function meterDecimate(kind: MeterKind, kept: number, value: number): number;
+/** A level's measurement, as METER_MEASUREMENTS spells it. */
+export type MeterMeasurement = (typeof METER_MEASUREMENTS)[number];
+/** A meter's unit, as METER_UNITS spells it (its label in METER_UNITS_LABELS). */
+export type MeterUnit = (typeof METER_UNITS)[number];
+/** The unit a meter's values are in: a level's from its measurement, a gain reduction's dB. Twin of omx_meter_view_unit_of. */
+export declare function meterUnitOf(kind: MeterKind, measurement: MeterMeasurement): MeterUnit;
+/** The gain-reduction reading's hold, ms: OMX_METER_GR_HOLD_MS of mix/omx_meter.h (the oracle pins it). */
+export declare const METER_GR_HOLD_MS = 300;
+/** One gain-reduction reading, the state of struct omx_meter_gr: the reading (dB, <= 0) and the hold still owed (s). */
+export interface MeterGr {
+    readonly db: number;
+    readonly holdLeftS: number;
+}
+/** No reduction, no hold. */
+export declare const METER_GR_EMPTY: MeterGr;
+/**
+ * One step of a gain-reduction reading over `n` frames at `sr`: a block as deep or deeper replaces it and restarts the
+ * hold; a shallower one spends the hold, then the reading closes on it as a linear gain by `releasePole^n`, and lands
+ * within 0.001 dB. Float arithmetic, as the kernel's. Twin of omx_meter_gr_step.
+ */
+export declare function meterGrStep(m: MeterGr, blockDb: number, n: number, sr: number, releasePole: number): MeterGr;
+/** The gain-reduction reading at the reader's tick: meterGrStep over the frames `dtS` seconds cover at `sr`. Twin of omx_meter_view_gr. */
+export declare function meterGrView(m: MeterGr, deepestDb: number, dtS: number, sr: number, releasePole: number): MeterGr;

package/dist/meter.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The meter view law, the twin of mix/omx_meter_view.h: how a measured value is drawn, the same on every surface.
+ * The fill of a dB scale from the floor to 0 dBFS, the peak marker that takes a louder value at once and falls by
+ * elapsed time (the same seconds give the same fall at any draw rate, and it falls on silence), the clip word that
+ * stays lit until cleared, the stepped count of an LED ladder with its hysteresis (a bar has no release), the
+ * gain-reduction reading recovered by the time elapsed at the reader's tick (the twin of omx_meter_gr_step), and what a
+ * decimating subscriber keeps. The numbers are METER_VIEW, declared in data/primitives/meter.json. Pinned by
+ * test/meter.test.mjs: against the kernel through the oracle at the nine oracle rates, and against
+ * vectors/meter-view.json, the file every copy of the law reads.
+ */
+import { LIN_TO_DB_FLOOR, METER_DECIMATION, METER_KINDS, METER_MEASUREMENTS, METER_UNITS_LABELS, METER_VIEW } from './definitions.js';
+/** The wire words of the meter sets, in value order: `gain-reduction`, `true-peak`, `lufs-m`…; units as labelled. */
+export const METER_WORDS = {
+    kinds: METER_KINDS.map((id) => id.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)),
+    measurements: METER_MEASUREMENTS.map((id) => id.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)),
+    units: [...METER_UNITS_LABELS],
+};
+/** `x` held to 0..1; NaN reads 0. */
+const unit = (x) => (x > 0 ? (x < 1 ? x : 1) : 0);
+/** The fill of a dB level, linear in dB from `floorDb` (0) to 0 dBFS (1); NaN and -Infinity read 0. Twin of omx_meter_view_fill_db. */
+export function meterFillDb(db, floorDb = METER_VIEW.floorDb) {
+    if (!(db > floorDb))
+        return 0;
+    if (db >= 0)
+        return 1;
+    return (db - floorDb) / -floorDb;
+}
+/** The fill of a linear peak (1 is 0 dBFS) on the same dB scale. Twin of omx_meter_view_fill. */
+export function meterFill(level, floorDb = METER_VIEW.floorDb) {
+    if (!(level > 0))
+        return 0;
+    if (level >= 1)
+        return 1;
+    return meterFillDb(20 * Math.log10(level), floorDb);
+}
+/** A fresh marker: empty. */
+export const METER_MARKER_EMPTY = { peak: 0, elapsedS: 0, live: 0, marker: 0 };
+/**
+ * One draw tick of the peak marker: a fill at or above it is taken at once; below it the marker falls
+ * `fallDbPerSecond` for each second elapsed since it took its value, never under the live fill. `dtS` is the time
+ * since the last tick (negative or NaN counts as 0). Twin of omx_meter_view_step.
+ */
+export function meterMarker(prev, fill, dtS, fallDbPerSecond = METER_VIEW.fallDbPerSecond, floorDb = METER_VIEW.floorDb) {
+    const p = prev ?? METER_MARKER_EMPTY;
+    const f = unit(fill);
+    const elapsedS = p.elapsedS + (dtS > 0 ? dtS : 0);
+    const m = p.peak - (fallDbPerSecond * elapsedS) / -floorDb;
+    if (!(m > f))
+        return { peak: f, elapsedS: 0, live: f, marker: f };
+    return { peak: p.peak, elapsedS, live: f, marker: m };
+}
+/** The clip word for one tick: lit by a clip, and lit until the surface clears it (sets it false). Twin of omx_meter_view_clip. */
+export function meterClip(lit, clip) {
+    return lit || clip;
+}
+/**
+ * A stepped display's count (an LED ladder of `steps` segments) with hysteresis against the count it showed last: it
+ * holds while the unrounded value stays within `0.5 + hysteresis` steps of it. `prevStep` undefined (or negative) is a
+ * fresh or reset strip: plain rounding. Twin of omx_meter_view_ladder.
+ */
+export function meterStep(prevStep, fill, steps, hysteresis = METER_VIEW.stepHysteresis) {
+    const raw = unit(fill) * steps;
+    if (prevStep !== undefined && prevStep >= 0 && Math.abs(raw - prevStep) <= 0.5 + hysteresis)
+        return prevStep;
+    return Math.floor(raw + 0.5);
+}
+/** A stepped BAR for one tick: a linear peak to its fill, then its count against the last one. No release. Twin of omx_meter_view_bar_step. */
+export function meterBarStep(prevStep, level, steps, hysteresis = METER_VIEW.stepHysteresis) {
+    return meterStep(prevStep, meterFill(level), steps, hysteresis);
+}
+/** What a decimating subscriber keeps of two frames (METER_DECIMATION): a level the peak, a gain reduction the deepest; a NaN frame is never kept. Twin of omx_meter_view_decimate. */
+export function meterDecimate(kind, kept, value) {
+    if (METER_DECIMATION[METER_KINDS.indexOf(kind)] === 'deepest')
+        return value < kept ? value : kept;
+    return value > kept ? value : kept;
+}
+const UNIT_OF = { peak: 'dbfs', truePeak: 'dbtp', lufsM: 'lufs', lufsS: 'lufs', lufsI: 'lufs', lra: 'lu' };
+/** The unit a meter's values are in: a level's from its measurement, a gain reduction's dB. Twin of omx_meter_view_unit_of. */
+export function meterUnitOf(kind, measurement) {
+    return kind === 'gainReduction' ? 'db' : UNIT_OF[measurement];
+}
+/** The gain-reduction reading's hold, ms: OMX_METER_GR_HOLD_MS of mix/omx_meter.h (the oracle pins it). */
+export const METER_GR_HOLD_MS = 300;
+/** No reduction, no hold. */
+export const METER_GR_EMPTY = { db: 0, holdLeftS: 0 };
+const f32 = Math.fround;
+/**
+ * One step of a gain-reduction reading over `n` frames at `sr`: a block as deep or deeper replaces it and restarts the
+ * hold; a shallower one spends the hold, then the reading closes on it as a linear gain by `releasePole^n`, and lands
+ * within 0.001 dB. Float arithmetic, as the kernel's. Twin of omx_meter_gr_step.
+ */
+export function meterGrStep(m, blockDb, n, sr, releasePole) {
+    const dt = f32(f32(n) / f32(sr));
+    const b = f32(blockDb);
+    if (b <= m.db)
+        return { db: b, holdLeftS: f32(f32(METER_GR_HOLD_MS) * f32(0.001)) };
+    if (m.holdLeftS > 0)
+        return { db: m.db, holdLeftS: f32(m.holdLeftS - dt) };
+    const pole = f32(releasePole);
+    const k = pole >= 0 && pole < 1 ? f32(Math.pow(pole, f32(n))) : 0;
+    const lin = (db) => f32(Math.pow(10, f32(db * f32(0.05))));
+    const want = lin(b);
+    const g = f32(want + f32(f32(lin(m.db) - want) * k));
+    let db = f32(f32(20) * f32(Math.log10(g < f32(LIN_TO_DB_FLOOR.lin) ? f32(LIN_TO_DB_FLOOR.lin) : g)));
+    if (!(db < f32(b - f32(0.001))))
+        db = b;
+    return { db, holdLeftS: m.holdLeftS };
+}
+/** The gain-reduction reading at the reader's tick: meterGrStep over the frames `dtS` seconds cover at `sr`. Twin of omx_meter_view_gr. */
+export function meterGrView(m, deepestDb, dtS, sr, releasePole) {
+    return meterGrStep(m, deepestDb, dtS > 0 ? Math.floor(dtS * sr + 0.5) : 0, sr, releasePole);
+}