@openmixer/omx-dsp 0.31.0 → 0.32.1

package/dist/curve.d.ts

@@ -12,6 +12,8 @@ export declare const CURVE_WORDS: {
     readonly roles: string[];
     readonly units: string[];
     readonly shapes: string[];
+    /** fbs-fixed and fbs-live: the origins are spelt with a hyphen */
+    readonly origins: string[];
 };
 /** What curvePoints answers when it draws nothing: a CURVE_CODES id other than `ok`. */
 export type CurveCode = Exclude<(typeof CURVE_CODES)[number], 'ok'>;
@@ -27,6 +29,8 @@ export interface CurveTerm {
     readonly unit: string;
     /** For `band_type`, the shape its value selects (from the role's `shapes`); for `band_freq`, the fixed shape. */
     readonly shape?: string;
+    /** Where the band comes from: `user` (the default), `fbs-fixed` or `fbs-live`. A band's is its band_freq term's. */
+    readonly origin?: string;
 }
 /** A curve request: one display of the description, bound. */
 export interface CurveRequest {
@@ -45,6 +49,15 @@ export interface CurveRequest {
     };
     /** The terms; a later term of one role and index replaces an earlier. */
     readonly terms: readonly CurveTerm[];
+    /** Also answer the curve over the `user` bands alone, at the same x. */
+    readonly userOnly?: boolean;
+}
+/** A band whose origin is not `user`: its centre (Hz), its own magnitude there (dB), its Q and its origin. */
+export interface CurveMark {
+    readonly freq: number;
+    readonly depthDb: number;
+    readonly q: number;
+    readonly origin: string;
 }
 /** One point: Hz and dB for an EQ, input dB and output dB for a transfer curve. */
 export interface CurvePoint {
@@ -54,6 +67,10 @@ export interface CurvePoint {
 /** The answer: the points, ascending in x, or the code of what is missing or refused. */
 export type CurveAnswer = {
     readonly points: readonly CurvePoint[];
+    /** One per drawn band whose origin is not `user`, in band order; none for a transfer curve. */
+    readonly marks: readonly CurveMark[];
+    /** With `userOnly`: the curve over the user bands (and the head filters) alone, at the same x. */
+    readonly userPoints?: readonly CurvePoint[];
 } | {
     readonly code: CurveCode;
 };

package/dist/curve.js

@@ -6,8 +6,8 @@
  * words) and the same codes (CURVE_CODES), checked in the same order. Pinned by test/agreement.test.mjs at the
  * nine oracle rates: the EQ through the magnitude twins, the transfer curves through the gain computer twins.
  */
-import { COMP_KNEE_DB_RANGE, COMP_RATIO_RANGE, CURVE_DISPLAYS, CURVE_EXTENTS, CURVE_FAMILIES, CURVE_POINTS_MAX, CURVE_ROLES, CURVE_SHAPES, CURVE_UNITS, GATE_RANGE_DB_RANGE, GATE_RATIO_RANGE, LIN_TO_DB_FLOOR, } from './definitions.js';
-import { magnitudeSumDb, octavesToQ } from './eq.js';
+import { COMP_KNEE_DB_RANGE, COMP_RATIO_RANGE, CURVE_DISPLAYS, CURVE_EXTENTS, CURVE_FAMILIES, CURVE_ORIGINS, CURVE_POINTS_MAX, CURVE_ROLES, CURVE_SHAPES, CURVE_UNITS, EQ_BAND_DEFAULTS, GATE_RANGE_DB_RANGE, GATE_RATIO_RANGE, LIN_TO_DB_FLOOR, } from './definitions.js';
+import { clampEqQFor, magnitudeSumDb, octavesToQ } from './eq.js';
 import { gaincompDb, gaincompDbShifted, gateKnee } from './gaincomp.js';
 /** A set id as the description spells it: `eqResponse` is `eq_response`; the unshaped band is `-`. */
 const wordOf = (id) => (id === 'unshaped' ? '-' : id.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`));
@@ -18,6 +18,8 @@ export const CURVE_WORDS = {
     roles: CURVE_ROLES.map(wordOf),
     units: CURVE_UNITS.map(wordOf),
     shapes: CURVE_SHAPES.map(wordOf),
+    /** fbs-fixed and fbs-live: the origins are spelt with a hyphen */
+    origins: CURVE_ORIGINS.map((id) => id.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)),
 };
 /** The units each role converts from (omx_curve_unit_accepted). */
 const ACCEPTS = {
@@ -46,6 +48,7 @@ const valueOf = (t) => {
 };
 const SHAPE_TYPE = {
     bell: 'bell', lowshelf: 'lowshelf', highshelf: 'highshelf', highpass: 'highpass', lowpass: 'lowpass', notch: 'notch',
+    allpass1: 'allpass1', allpass2: 'allpass2',
 };
 /** The Q of each section of a Butterworth head filter (omx_eq_butterworth_qs): 12 dB/oct one at 1/sqrt(2), 24 dB/oct
  *  two whose product is maximally flat, the kernel's own digits. */
@@ -89,7 +92,7 @@ export function curvePoints(rq) {
         return { code: 'valueNotFinite' };
     if (rq.terms.some((t) => !Number.isFinite(t.value)))
         return { code: 'valueNotFinite' };
-    if (rq.terms.some((t) => !ACCEPTS[t.role]?.includes(t.unit)))
+    if (rq.terms.some((t) => !ACCEPTS[t.role]?.includes(t.unit) || !CURVE_WORDS.origins.includes(t.origin ?? 'user')))
         return { code: 'unitRefused' };
     let lo, hi;
     if (rq.extents)
@@ -122,6 +125,7 @@ function eqPoints(rq, find, lo, hi) {
         nb = Math.max(nb, i + 1);
     }
     const bands = [];
+    const origin = [];
     for (let b = 0; b < nb; b++) {
         const type = find('band_type', b), freq = find('band_freq', b), gain = find('band_gain', b), q = find('band_q', b), on = find('band_on', b);
         if (!type && !freq && !gain && !q && !on)
@@ -131,19 +135,18 @@ function eqPoints(rq, find, lo, hi) {
         const shape = type?.shape ?? freq.shape;
         if (shape === undefined)
             return { code: 'termMissing' };
-        if (shape === 'off')
-            continue;
         const kind = SHAPE_TYPE[shape];
         if (!kind)
-            return { code: 'kindUnknown' };
-        if (!q)
-            return { code: 'termMissing' };
+            continue; // off, or a choice with no shape (`-`): not drawn
         const gains = kind === 'bell' || kind === 'lowshelf' || kind === 'highshelf';
         if (gains && !gain)
             return { code: 'termMissing' };
         if (on && valueOf(on) === 0)
             continue;
-        bands.push({ type: kind, freq: valueOf(freq), gainDb: gains && gain ? valueOf(gain) : 0, q: valueOf(q) });
+        bands.push({ type: kind, freq: valueOf(freq), gainDb: gains && gain ? valueOf(gain) : 0,
+            // no Q control: the declared default (EQ_BAND_DEFAULTS), clamped for the shape as the kernel clamps it
+            q: q ? valueOf(q) : Math.fround(clampEqQFor(kind === 'notch' ? 'notch' : 'bell', EQ_BAND_DEFAULTS.q)) });
+        origin.push(freq.origin ?? 'user');
     }
     const pass = [];
     let present = false;
@@ -152,7 +155,8 @@ function eqPoints(rq, find, lo, hi) {
         if (!fr && !sl && !on)
             continue;
         present = true;
-        if (!fr || !sl)
+        // the slope in dB per octave, from the role's declared enumeration or a dB control; a bare choice value is none
+        if (!fr || !sl || sl.unit !== 'db')
             return { code: 'termMissing' };
         const slope = valueOf(sl);
         if (slope !== 12 && slope !== 24)
@@ -170,20 +174,24 @@ function eqPoints(rq, find, lo, hi) {
     if (rq.points + 3 * drawn.length > CURVE_POINTS_MAX)
         return { code: 'pointsRange' };
     const top = (rq.sampleRate / 2) * 0.999;
-    const points = curveFreqs(drawn, lo, hi, rq.points).map((x) => ({
-        x,
-        y: magnitudeSumDb(drawn, x < top ? x : top, rq.sampleRate, CURVE_EXTENTS.eqFloorDb),
-    }));
-    return { points };
+    const xs = curveFreqs(drawn, lo, hi, rq.points);
+    const sum = (set) => xs.map((x) => ({ x, y: magnitudeSumDb(set, x < top ? x : top, rq.sampleRate, CURVE_EXTENTS.eqFloorDb) }));
+    const marks = bands.flatMap((b, i) => origin[i] === 'user' ? [] : [{ freq: b.freq, depthDb: magnitudeSumDb([b], b.freq, rq.sampleRate, CURVE_EXTENTS.eqFloorDb), q: b.q, origin: origin[i] }]);
+    const points = sum(drawn);
+    if (!rq.userOnly)
+        return { points, marks };
+    return { points, marks, userPoints: sum([...bands.filter((_, i) => origin[i] === 'user'), ...pass]) };
 }
 function transferPoints(rq, find, lo, hi) {
     const below = rq.family === 'gate';
     const thr = find('threshold'), ratio = find('ratio'), knee = find('knee'), makeup = find('makeup'), range = find('range');
     const ks = find('knee_start'), ke = find('knee_end');
-    if (!thr || !ratio || (below && !range) || (below && !ks !== !ke))
+    // a limiter has no ratio role: the dynamics form at ratio infinity, a hard corner at the threshold
+    const limiter = rq.family === 'limiter';
+    if (!thr || (!ratio && !limiter) || (below && !range) || (below && !ks !== !ke))
         return { code: 'termMissing' };
     const f = Math.fround;
-    const r = f(valueOf(ratio)), k = knee ? f(valueOf(knee)) : 0;
+    const r = ratio ? f(valueOf(ratio)) : Infinity, k = knee ? f(valueOf(knee)) : 0;
     const rmin = f(below ? GATE_RATIO_RANGE.min : COMP_RATIO_RANGE.min);
     const thresh = f(valueOf(thr));
     let kneeDb = k < COMP_KNEE_DB_RANGE.min ? COMP_KNEE_DB_RANGE.min : k;
@@ -204,5 +212,5 @@ function transferPoints(rq, find, lo, hi) {
         const g = below ? gaincompDbShifted(p, shiftDb, lv) : gaincompDb(p, lv);
         points.push({ x: lv, y: lv + g + mk });
     }
-    return { points };
+    return rq.userOnly ? { points, marks: [], userPoints: points } : { points, marks: [] };
 }

package/dist/definitions.d.ts

@@ -13,6 +13,47 @@ export declare const LOWPASS_HANDOVER: {
     readonly hiAtLoQ: 0.9;
     readonly hiAtPeakQ: 0.8;
 };
+/** What every band of a fresh EQ comes up at, whatever its type and its strip: flat (0 dB) and Q 1. The band frequencies and types come from the default rule. @see data/kernels/eq.json */
+export declare const EQ_BAND_DEFAULTS: {
+    readonly gainDb: 0;
+    readonly q: 1;
+};
+/** The deepest cut a band of an fbs-* origin may hold, in dB: the feedback corrector's own safety bound, never the operator EQ's ±15 (EQ_GAIN_RANGE), which stays the bound of every other origin. Declared here as one value until the vocabulary owner (omx-contract) carries it as its own word, a new ref beside EQ_GAIN_RANGE and never a widening of it; this item then becomes that ref, and no second copy of the number is ever written. (dB) @see data/kernels/fbs.json */
+export declare const FBS_MAX_CUT_DB = -24;
+/** How much deeper a live band's full depth goes each time regrowth re-clamps a release, in dB, down to FBS_MAX_CUT_DB: regrowth at a depth is the measurement that the depth was not enough. (dB) @see data/kernels/fbs.json */
+export declare const FBS_RECLAMP_DEEPEN_DB = 3;
+/** The most times the clean hold doubles after re-clamps: the hold before the first release stage is the channel's hold times 2^min(re-clamps, this). @see data/kernels/fbs.json */
+export declare const FBS_RECLAMP_BACKOFF_CAP = 3;
+/** How long one release stage's gain ramp takes, in ms, from the depth the band stands at to the stage's depth. (ms) @see data/kernels/fbs.json */
+export declare const FBS_LIFT_RAMP_MS = 3000;
+/** The equal steps one release ramp takes, FBS_LIFT_RAMP_MS / this apart: the last step lands the stage's depth exactly. @see data/kernels/fbs.json */
+export declare const FBS_LIFT_RAMP_STEPS = 10;
+/** Each release stage holds the planted depth times this ratio to the stage's power: every stage releases a third of what remains. @see data/kernels/fbs.json */
+export declare const FBS_RELEASE_RATIO = 0.6666666666666666;
+/** A release stage whose depth is shallower than this, in dB, removes the band instead of holding it: the cut is inaudible. (dB) @see data/kernels/fbs.json */
+export declare const FBS_RELEASE_DONE_DB = 1;
+/** How long a band listens at an eased stage, clean, before the next stage begins, in ms. (ms) @see data/kernels/fbs.json */
+export declare const FBS_RELEASE_DWELL_MS = 8000;
+/** The lowest frequency a confirmed ring is planted at, in Hz; one below it is refused as rejected-edge, never clamped onto the EQ's edge. (Hz) @see data/kernels/fbs.json */
+export declare const FBS_RING_HZ_MIN = 60;
+/** The highest frequency a confirmed ring is planted at, in Hz; one above it is refused as rejected-edge. (Hz) @see data/kernels/fbs.json */
+export declare const FBS_RING_HZ_MAX = 16000;
+/** Two readings are the same ringing frequency within this many Hz, or FBS_SAME_RING_SHARE of the higher one, whichever is wider. (Hz) @see data/kernels/fbs.json */
+export declare const FBS_SAME_RING_HZ = 3;
+/** The share of the higher frequency within which two readings are the same ringing frequency, when it is wider than FBS_SAME_RING_HZ: FFT bin spacing grows with frequency. @see data/kernels/fbs.json */
+export declare const FBS_SAME_RING_SHARE = 0.015;
+/** The clean hold, in seconds, before a live band's first release stage. (s) @see data/kernels/fbs.json */
+export declare const FBS_DEFAULT_HOLD_SECONDS = 5;
+/** How many bands one corrector may plant when nobody set its cap; a full pool plants nothing and says pool-full. @see data/kernels/fbs.json */
+export declare const FBS_DEFAULT_MAX_AUTO_BANDS = 6;
+/** The merge radius, in cents: a confirmed ring this close to a band already planted is that band's find, and plants nothing. (cents) @see data/kernels/fbs.json */
+export declare const FBS_DEFAULT_MERGE_CENTS = 100;
+/** How long a fully released find's re-clamp count is remembered, in seconds, so a chronic ringer re-plants with its doubled holds. (s) @see data/kernels/fbs.json */
+export declare const FBS_DEFAULT_COOLDOWN_SECONDS = 600;
+/** Default planted-notch width (Q) — the dbx-AFS-style ultra-narrow notch the corrector plants. `addBand`'s per-shape clamp holds it at 116 for a fixed notch and narrows it to 8 for a live bell, so this is the declared starting point rather than the width every notch ends up with. @see data/kernels/fbs.json */
+export declare const FBS_DEFAULT_NOTCH_Q = 116;
+/** Released finds the ring memory holds at once. The console's list is unbounded and expires by FBS_DEFAULT_COOLDOWN_SECONDS; a full memory here forgets its oldest entry first, and counts it. @see data/kernels/fbs.json */
+export declare const FBS_RING_MEMORY_SLOTS = 32;
 /** The displays a panel description draws from a closed form, the kinds omx_curve_points answers: an EQ's magnitude response, x in Hz and y in dB, and a dynamics stage's static transfer curve, input dB to output dB. The wire spells each id in snake case (`eq_response`, `transfer_curve`), the description's own display word. @see data/primitives/curve.json */
 export declare const CURVE_DISPLAYS: readonly ["eqResponse", "transferCurve"];
 /** The panel families omx_curve_points draws, by the description's family word. `eq` draws an eq_response; the other four a transfer_curve, the family choosing the gain computer's mode: `dynamics`, `limiter` and `deesser` act ABOVE the threshold, `gate` BELOW it with the shifted knee of the gate's knee range. Any other family has no closed form here. @see data/primitives/curve.json */
@@ -21,9 +62,11 @@ export declare const CURVE_FAMILIES: readonly ["eq", "dynamics", "limiter", "gat
 export declare const CURVE_ROLES: readonly ["bandType", "bandFreq", "bandGain", "bandQ", "bandOn", "hpfFreq", "hpfSlope", "hpfOn", "lpfFreq", "lpfSlope", "lpfOn", "threshold", "ratio", "knee", "makeup", "range", "kneeStart", "kneeEnd"];
 /** The units a curve term's value may come in, the param-contract extension's unit tokens the served description gives a role. omx_curve_points converts once: `coef` to dB for a gain, `oct` to Q for a bandwidth, `khz` to Hz; a level in `db`, `dbfs`, `dbu` or `lufs` is read as dB from the threshold's own scale; `none` is a plain number, a switch or a choice; `ratio` a ratio. A unit its role does not accept is refused. @see data/primitives/curve.json */
 export declare const CURVE_UNITS: readonly ["hz", "khz", "db", "dbfs", "dbu", "lufs", "coef", "oct", "none", "ratio"];
-/** The shape of an EQ band, as the caller resolves it from the description: a `band_type` role's `shapes` list indexed by the control's choice value, or the fixed `shape` of a band no control selects. `off` is a band that is not drawn; `unshaped`, spelt `-` on the wire, a choice value with no closed form, which no curve is drawn from. The others design the band through omx_eq_design: a bell, the two shelves, the pass filters and the notch. @see data/primitives/curve.json */
-export declare const CURVE_SHAPES: readonly ["off", "bell", "lowshelf", "highshelf", "highpass", "lowpass", "notch", "unshaped"];
-/** What omx_curve_points answers in its code: `ok`, a curve; `kindUnknown`, a kind, family, shape or slope with no closed form; `termMissing`, a term the model needs is not in the request (a band's frequency, shape and Q, a bell's or shelf's gain, a head filter's corner and slope; threshold and ratio for an ABOVE family; threshold, range and ratio for a gate; both ends of a gate's knee range or neither); `unitRefused`, a term in a unit its role does not accept; `valueNotFinite`, a value, the rate or an extent that is not finite, a rate that is not positive; `pointsRange`, grid points outside 2 to CURVE_POINTS_MAX (for an EQ, with three anchors a drawn band), a band index past what fits, or extents that bound nothing; `room`, a caller's buffers too small for the points. No curve is drawn from a guess: a missing term is a code, never a default. @see data/primitives/curve.json */
+/** The shape of an EQ band, as the caller resolves it from the description: a `band_type` role's `shapes` list indexed by the control's choice value, or the fixed `shape` of a band no control selects. `off` is a band that is not drawn, and so is `unshaped`, spelt `-` on the wire, a choice value with no shape. The others design the band through omx_eq_design: a bell, the two shelves, the pass filters, the notch, and the first- and second-order allpasses, which draw what they run, 0 dB. @see data/primitives/curve.json */
+export declare const CURVE_SHAPES: readonly ["off", "bell", "lowshelf", "highshelf", "highpass", "lowpass", "notch", "unshaped", "allpass1", "allpass2"];
+/** Where an EQ band of a curve request comes from, as the console's strip EQ state says it (its BAND_ORIGINS): `user`, the operator's own band, and the bands a planter put there, `fbsFixed` and `fbsLive` (the feedback corrector's ring-out and show pools), `hrp` (the harmonic resonance processor's cuts) and `roomMode` (a room mode's correction), spelt `user`, `fbs-fixed`, `fbs-live`, `hrp` and `room-mode` on the wire. The sum ignores it: every drawn band is in the curve. A band whose origin is not `user` is answered as a mark (its frequency, depth, Q and origin), and a request that asks for it also gets the curve over the `user` bands alone. A plugin's descriptor carries no origin: a request with none draws no marks. @see data/primitives/curve.json */
+export declare const CURVE_ORIGINS: readonly ["user", "fbsFixed", "fbsLive", "hrp", "roomMode"];
+/** What omx_curve_points answers in its code: `ok`, a curve; `kindUnknown`, a kind, family or head filter slope with no closed form; `termMissing`, a term the closed form has no default for is not in the request (a band's frequency and shape, a bell's or shelf's gain, a head filter's corner, and its slope unless it comes from the role's declared enumeration as dB per octave; threshold and ratio for dynamics and the de-esser, threshold for a limiter (its ratio is infinity, a hard corner), threshold, range and ratio for a gate; both ends of a gate's knee range or neither); `unitRefused`, a term in a unit its role does not accept; `valueNotFinite`, a value, the rate or an extent that is not finite, a rate that is not positive; `pointsRange`, grid points outside 2 to CURVE_POINTS_MAX (for an EQ, with three anchors a drawn band), a band index past what fits, or extents that bound nothing; `room`, a caller's buffers too small. Where omx-dsp declares a default the curve takes it: a band's Q is EQ_BAND_DEFAULTS q, clamped for its shape as clampEqQFor clamps it. No curve is drawn from a guess. @see data/primitives/curve.json */
 export declare const CURVE_CODES: readonly ["ok", "kindUnknown", "termMissing", "unitRefused", "valueNotFinite", "pointsRange", "room"];
 /** The most points one curve carries, an EQ's band anchors included: a reply of x with four significant digits and y to 0.01 dB, about 13 bytes a point, fits the 4096-byte line a host's reply is built in. Every caller reads it here; it moves with that buffer, in this one place. @see data/primitives/curve.json */
 export declare const CURVE_POINTS_MAX = 256;
@@ -41,6 +84,24 @@ export declare const LIN_TO_DB_FLOOR: {
     readonly lin: 1e-9;
     readonly db: -180;
 };
+/** A meter's view law, the same on every surface: the fill is linear in dB from `floorDb` (dBFS, an empty display) to 0 dBFS (a full one); a stepped display (an LED ladder) holds its count until the level moves `stepHysteresis` of a step past the count's own rounding edge; the peak marker falls `fallDbPerSecond` dB for each second elapsed at the view's draw tick, whatever the tick's rate, silence included. A host reads a plugin's held meter at `hostReadHz`; the console streams meter values at `streamHz`. dBFS, a fraction of a step, dB per second and Hz. @see data/primitives/meter.json */
+export declare const METER_VIEW: {
+    readonly floorDb: -60;
+    readonly stepHysteresis: 0.25;
+    readonly fallDbPerSecond: 18;
+    readonly hostReadHz: 50;
+    readonly streamHz: 20;
+};
+/** What a meter measures, as a plugin's descriptor and the panel description spell it: `level`, a signal level (its measurement one of METER_MEASUREMENTS), and `gainReduction`, the gain a dynamics stage takes off, dB at or below 0. The wire spells them `level` and `gain-reduction`. `rms`, `vu` and `ppm` are not kinds. @see data/primitives/meter.json */
+export declare const METER_KINDS: readonly ["level", "gainReduction"];
+/** The measurement of a `level` meter: the sample peak (`peak`, dBFS), the true peak (`truePeak`, dBTP), and the loudness measures of omx_loudness.h: momentary, short-term and integrated loudness (`lufsM`, `lufsS`, `lufsI`, LUFS) and the loudness range (`lra`, LU). The wire spells them `peak`, `true-peak`, `lufs-m`, `lufs-s`, `lufs-i` and `lra`. A foreign meter's measurement is null, never guessed. @see data/primitives/meter.json */
+export declare const METER_MEASUREMENTS: readonly ["peak", "truePeak", "lufsM", "lufsS", "lufsI", "lra"];
+/** The unit a meter's values are in, spelt as its label: dBFS for a sample peak, dBTP for a true peak, LUFS for a loudness, LU for a loudness range, dB for a gain reduction. The scale a surface draws is captioned with it. @see data/primitives/meter.json */
+export declare const METER_UNITS: readonly ["dbfs", "dbtp", "lufs", "lu", "db"];
+/** The labels of METER_UNITS, in its order. @see data/primitives/meter.json */
+export declare const METER_UNITS_LABELS: readonly ["dBFS", "dBTP", "LUFS", "LU", "dB"];
+/** What a subscriber that decimates a meter stream keeps of the frames it drops, one per kind in METER_KINDS order, as the engine's slot keeps between two reads: a `level` keeps the `peak` (the largest value), a `gainReduction` the `deepest` (the smallest dB). Never the newest. @see data/primitives/meter.json */
+export declare const METER_DECIMATION: readonly ["peak", "deepest"];
 /** The Q (resonance) extent of a parametric band. @see data/kernels/eq.json */
 export declare const EQ_Q_RANGE: {
     readonly min: 0.3;
@@ -51,6 +112,36 @@ export declare const EQ_NOTCH_Q_RANGE: {
     readonly min: 0.3;
     readonly max: 116;
 };
+/** The parametric-band gain travel, in dB. The ± scalar `clampEqGain` enforces is READ off this (the engine derives its gain limit from `max`), so the bound is stated once and a surface cannot draw a wider knob than the clamp will honour. @see data/kernels/eq.json */
+export declare const EQ_GAIN_RANGE: {
+    readonly min: -15;
+    readonly max: 15;
+};
+/** The frequency band a parametric band can be dragged across. @see data/kernels/eq.json */
+export declare const EQ_FREQ_RANGE: {
+    readonly min: 20;
+    readonly max: 20000;
+};
+/** How many bands this corrector may plant at once (its pool), from one to the EQ's band count. An integer control. @see data/kernels/fbs.json */
+export declare const FBS_BANDS_RANGE: {
+    readonly min: 1;
+    readonly max: 24;
+};
+/** The clean hold, in seconds, before a live band's first release stage. @see data/kernels/fbs.json */
+export declare const FBS_HOLD_RANGE: {
+    readonly min: 1;
+    readonly max: 300;
+};
+/** The merge radius, in cents. An integer control. @see data/kernels/fbs.json */
+export declare const FBS_MERGE_RANGE: {
+    readonly min: 0;
+    readonly max: 600;
+};
+/** How long a released find's escalation is remembered, in seconds. An integer control. @see data/kernels/fbs.json */
+export declare const FBS_COOLDOWN_RANGE: {
+    readonly min: 0;
+    readonly max: 7200;
+};
 /** The travel of ratio, from its table COMP_LIMITS. @see data/kernels/comp.json */
 export declare const COMP_RATIO_RANGE: {
     readonly min: 1;

package/dist/definitions.js

@@ -16,6 +16,47 @@ export const LOWPASS_HANDOVER = {
     hiAtLoQ: 0.9,
     hiAtPeakQ: 0.8,
 };
+/** What every band of a fresh EQ comes up at, whatever its type and its strip: flat (0 dB) and Q 1. The band frequencies and types come from the default rule. @see data/kernels/eq.json */
+export const EQ_BAND_DEFAULTS = {
+    gainDb: 0,
+    q: 1,
+};
+/** The deepest cut a band of an fbs-* origin may hold, in dB: the feedback corrector's own safety bound, never the operator EQ's ±15 (EQ_GAIN_RANGE), which stays the bound of every other origin. Declared here as one value until the vocabulary owner (omx-contract) carries it as its own word, a new ref beside EQ_GAIN_RANGE and never a widening of it; this item then becomes that ref, and no second copy of the number is ever written. (dB) @see data/kernels/fbs.json */
+export const FBS_MAX_CUT_DB = -24;
+/** How much deeper a live band's full depth goes each time regrowth re-clamps a release, in dB, down to FBS_MAX_CUT_DB: regrowth at a depth is the measurement that the depth was not enough. (dB) @see data/kernels/fbs.json */
+export const FBS_RECLAMP_DEEPEN_DB = 3;
+/** The most times the clean hold doubles after re-clamps: the hold before the first release stage is the channel's hold times 2^min(re-clamps, this). @see data/kernels/fbs.json */
+export const FBS_RECLAMP_BACKOFF_CAP = 3;
+/** How long one release stage's gain ramp takes, in ms, from the depth the band stands at to the stage's depth. (ms) @see data/kernels/fbs.json */
+export const FBS_LIFT_RAMP_MS = 3000;
+/** The equal steps one release ramp takes, FBS_LIFT_RAMP_MS / this apart: the last step lands the stage's depth exactly. @see data/kernels/fbs.json */
+export const FBS_LIFT_RAMP_STEPS = 10;
+/** Each release stage holds the planted depth times this ratio to the stage's power: every stage releases a third of what remains. @see data/kernels/fbs.json */
+export const FBS_RELEASE_RATIO = 0.6666666666666666;
+/** A release stage whose depth is shallower than this, in dB, removes the band instead of holding it: the cut is inaudible. (dB) @see data/kernels/fbs.json */
+export const FBS_RELEASE_DONE_DB = 1;
+/** How long a band listens at an eased stage, clean, before the next stage begins, in ms. (ms) @see data/kernels/fbs.json */
+export const FBS_RELEASE_DWELL_MS = 8000;
+/** The lowest frequency a confirmed ring is planted at, in Hz; one below it is refused as rejected-edge, never clamped onto the EQ's edge. (Hz) @see data/kernels/fbs.json */
+export const FBS_RING_HZ_MIN = 60;
+/** The highest frequency a confirmed ring is planted at, in Hz; one above it is refused as rejected-edge. (Hz) @see data/kernels/fbs.json */
+export const FBS_RING_HZ_MAX = 16000;
+/** Two readings are the same ringing frequency within this many Hz, or FBS_SAME_RING_SHARE of the higher one, whichever is wider. (Hz) @see data/kernels/fbs.json */
+export const FBS_SAME_RING_HZ = 3;
+/** The share of the higher frequency within which two readings are the same ringing frequency, when it is wider than FBS_SAME_RING_HZ: FFT bin spacing grows with frequency. @see data/kernels/fbs.json */
+export const FBS_SAME_RING_SHARE = 0.015;
+/** The clean hold, in seconds, before a live band's first release stage. (s) @see data/kernels/fbs.json */
+export const FBS_DEFAULT_HOLD_SECONDS = 5;
+/** How many bands one corrector may plant when nobody set its cap; a full pool plants nothing and says pool-full. @see data/kernels/fbs.json */
+export const FBS_DEFAULT_MAX_AUTO_BANDS = 6;
+/** The merge radius, in cents: a confirmed ring this close to a band already planted is that band's find, and plants nothing. (cents) @see data/kernels/fbs.json */
+export const FBS_DEFAULT_MERGE_CENTS = 100;
+/** How long a fully released find's re-clamp count is remembered, in seconds, so a chronic ringer re-plants with its doubled holds. (s) @see data/kernels/fbs.json */
+export const FBS_DEFAULT_COOLDOWN_SECONDS = 600;
+/** Default planted-notch width (Q) — the dbx-AFS-style ultra-narrow notch the corrector plants. `addBand`'s per-shape clamp holds it at 116 for a fixed notch and narrows it to 8 for a live bell, so this is the declared starting point rather than the width every notch ends up with. @see data/kernels/fbs.json */
+export const FBS_DEFAULT_NOTCH_Q = 116;
+/** Released finds the ring memory holds at once. The console's list is unbounded and expires by FBS_DEFAULT_COOLDOWN_SECONDS; a full memory here forgets its oldest entry first, and counts it. @see data/kernels/fbs.json */
+export const FBS_RING_MEMORY_SLOTS = 32;
 /** The displays a panel description draws from a closed form, the kinds omx_curve_points answers: an EQ's magnitude response, x in Hz and y in dB, and a dynamics stage's static transfer curve, input dB to output dB. The wire spells each id in snake case (`eq_response`, `transfer_curve`), the description's own display word. @see data/primitives/curve.json */
 export const CURVE_DISPLAYS = ['eqResponse', 'transferCurve'];
 /** The panel families omx_curve_points draws, by the description's family word. `eq` draws an eq_response; the other four a transfer_curve, the family choosing the gain computer's mode: `dynamics`, `limiter` and `deesser` act ABOVE the threshold, `gate` BELOW it with the shifted knee of the gate's knee range. Any other family has no closed form here. @see data/primitives/curve.json */
@@ -24,9 +65,11 @@ export const CURVE_FAMILIES = ['eq', 'dynamics', 'limiter', 'gate', 'deesser'];
 export const CURVE_ROLES = ['bandType', 'bandFreq', 'bandGain', 'bandQ', 'bandOn', 'hpfFreq', 'hpfSlope', 'hpfOn', 'lpfFreq', 'lpfSlope', 'lpfOn', 'threshold', 'ratio', 'knee', 'makeup', 'range', 'kneeStart', 'kneeEnd'];
 /** The units a curve term's value may come in, the param-contract extension's unit tokens the served description gives a role. omx_curve_points converts once: `coef` to dB for a gain, `oct` to Q for a bandwidth, `khz` to Hz; a level in `db`, `dbfs`, `dbu` or `lufs` is read as dB from the threshold's own scale; `none` is a plain number, a switch or a choice; `ratio` a ratio. A unit its role does not accept is refused. @see data/primitives/curve.json */
 export const CURVE_UNITS = ['hz', 'khz', 'db', 'dbfs', 'dbu', 'lufs', 'coef', 'oct', 'none', 'ratio'];
-/** The shape of an EQ band, as the caller resolves it from the description: a `band_type` role's `shapes` list indexed by the control's choice value, or the fixed `shape` of a band no control selects. `off` is a band that is not drawn; `unshaped`, spelt `-` on the wire, a choice value with no closed form, which no curve is drawn from. The others design the band through omx_eq_design: a bell, the two shelves, the pass filters and the notch. @see data/primitives/curve.json */
-export const CURVE_SHAPES = ['off', 'bell', 'lowshelf', 'highshelf', 'highpass', 'lowpass', 'notch', 'unshaped'];
-/** What omx_curve_points answers in its code: `ok`, a curve; `kindUnknown`, a kind, family, shape or slope with no closed form; `termMissing`, a term the model needs is not in the request (a band's frequency, shape and Q, a bell's or shelf's gain, a head filter's corner and slope; threshold and ratio for an ABOVE family; threshold, range and ratio for a gate; both ends of a gate's knee range or neither); `unitRefused`, a term in a unit its role does not accept; `valueNotFinite`, a value, the rate or an extent that is not finite, a rate that is not positive; `pointsRange`, grid points outside 2 to CURVE_POINTS_MAX (for an EQ, with three anchors a drawn band), a band index past what fits, or extents that bound nothing; `room`, a caller's buffers too small for the points. No curve is drawn from a guess: a missing term is a code, never a default. @see data/primitives/curve.json */
+/** The shape of an EQ band, as the caller resolves it from the description: a `band_type` role's `shapes` list indexed by the control's choice value, or the fixed `shape` of a band no control selects. `off` is a band that is not drawn, and so is `unshaped`, spelt `-` on the wire, a choice value with no shape. The others design the band through omx_eq_design: a bell, the two shelves, the pass filters, the notch, and the first- and second-order allpasses, which draw what they run, 0 dB. @see data/primitives/curve.json */
+export const CURVE_SHAPES = ['off', 'bell', 'lowshelf', 'highshelf', 'highpass', 'lowpass', 'notch', 'unshaped', 'allpass1', 'allpass2'];
+/** Where an EQ band of a curve request comes from, as the console's strip EQ state says it (its BAND_ORIGINS): `user`, the operator's own band, and the bands a planter put there, `fbsFixed` and `fbsLive` (the feedback corrector's ring-out and show pools), `hrp` (the harmonic resonance processor's cuts) and `roomMode` (a room mode's correction), spelt `user`, `fbs-fixed`, `fbs-live`, `hrp` and `room-mode` on the wire. The sum ignores it: every drawn band is in the curve. A band whose origin is not `user` is answered as a mark (its frequency, depth, Q and origin), and a request that asks for it also gets the curve over the `user` bands alone. A plugin's descriptor carries no origin: a request with none draws no marks. @see data/primitives/curve.json */
+export const CURVE_ORIGINS = ['user', 'fbsFixed', 'fbsLive', 'hrp', 'roomMode'];
+/** What omx_curve_points answers in its code: `ok`, a curve; `kindUnknown`, a kind, family or head filter slope with no closed form; `termMissing`, a term the closed form has no default for is not in the request (a band's frequency and shape, a bell's or shelf's gain, a head filter's corner, and its slope unless it comes from the role's declared enumeration as dB per octave; threshold and ratio for dynamics and the de-esser, threshold for a limiter (its ratio is infinity, a hard corner), threshold, range and ratio for a gate; both ends of a gate's knee range or neither); `unitRefused`, a term in a unit its role does not accept; `valueNotFinite`, a value, the rate or an extent that is not finite, a rate that is not positive; `pointsRange`, grid points outside 2 to CURVE_POINTS_MAX (for an EQ, with three anchors a drawn band), a band index past what fits, or extents that bound nothing; `room`, a caller's buffers too small. Where omx-dsp declares a default the curve takes it: a band's Q is EQ_BAND_DEFAULTS q, clamped for its shape as clampEqQFor clamps it. No curve is drawn from a guess. @see data/primitives/curve.json */
 export const CURVE_CODES = ['ok', 'kindUnknown', 'termMissing', 'unitRefused', 'valueNotFinite', 'pointsRange', 'room'];
 /** The most points one curve carries, an EQ's band anchors included: a reply of x with four significant digits and y to 0.01 dB, about 13 bytes a point, fits the 4096-byte line a host's reply is built in. Every caller reads it here; it moves with that buffer, in this one place. @see data/primitives/curve.json */
 export const CURVE_POINTS_MAX = 256;
@@ -44,10 +87,40 @@ export const LIN_TO_DB_FLOOR = {
     lin: 1e-9,
     db: -180,
 };
+/** A meter's view law, the same on every surface: the fill is linear in dB from `floorDb` (dBFS, an empty display) to 0 dBFS (a full one); a stepped display (an LED ladder) holds its count until the level moves `stepHysteresis` of a step past the count's own rounding edge; the peak marker falls `fallDbPerSecond` dB for each second elapsed at the view's draw tick, whatever the tick's rate, silence included. A host reads a plugin's held meter at `hostReadHz`; the console streams meter values at `streamHz`. dBFS, a fraction of a step, dB per second and Hz. @see data/primitives/meter.json */
+export const METER_VIEW = {
+    floorDb: -60,
+    stepHysteresis: 0.25,
+    fallDbPerSecond: 18,
+    hostReadHz: 50,
+    streamHz: 20,
+};
+/** What a meter measures, as a plugin's descriptor and the panel description spell it: `level`, a signal level (its measurement one of METER_MEASUREMENTS), and `gainReduction`, the gain a dynamics stage takes off, dB at or below 0. The wire spells them `level` and `gain-reduction`. `rms`, `vu` and `ppm` are not kinds. @see data/primitives/meter.json */
+export const METER_KINDS = ['level', 'gainReduction'];
+/** The measurement of a `level` meter: the sample peak (`peak`, dBFS), the true peak (`truePeak`, dBTP), and the loudness measures of omx_loudness.h: momentary, short-term and integrated loudness (`lufsM`, `lufsS`, `lufsI`, LUFS) and the loudness range (`lra`, LU). The wire spells them `peak`, `true-peak`, `lufs-m`, `lufs-s`, `lufs-i` and `lra`. A foreign meter's measurement is null, never guessed. @see data/primitives/meter.json */
+export const METER_MEASUREMENTS = ['peak', 'truePeak', 'lufsM', 'lufsS', 'lufsI', 'lra'];
+/** The unit a meter's values are in, spelt as its label: dBFS for a sample peak, dBTP for a true peak, LUFS for a loudness, LU for a loudness range, dB for a gain reduction. The scale a surface draws is captioned with it. @see data/primitives/meter.json */
+export const METER_UNITS = ['dbfs', 'dbtp', 'lufs', 'lu', 'db'];
+/** The labels of METER_UNITS, in its order. @see data/primitives/meter.json */
+export const METER_UNITS_LABELS = ['dBFS', 'dBTP', 'LUFS', 'LU', 'dB'];
+/** What a subscriber that decimates a meter stream keeps of the frames it drops, one per kind in METER_KINDS order, as the engine's slot keeps between two reads: a `level` keeps the `peak` (the largest value), a `gainReduction` the `deepest` (the smallest dB). Never the newest. @see data/primitives/meter.json */
+export const METER_DECIMATION = ['peak', 'deepest'];
 /** 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 };
+/** The parametric-band gain travel, in dB. The ± scalar `clampEqGain` enforces is READ off this (the engine derives its gain limit from `max`), so the bound is stated once and a surface cannot draw a wider knob than the clamp will honour. @see data/kernels/eq.json */
+export const EQ_GAIN_RANGE = { min: -15, max: 15 };
+/** The frequency band a parametric band can be dragged across. @see data/kernels/eq.json */
+export const EQ_FREQ_RANGE = { min: 20, max: 20000 };
+/** How many bands this corrector may plant at once (its pool), from one to the EQ's band count. An integer control. @see data/kernels/fbs.json */
+export const FBS_BANDS_RANGE = { min: 1, max: 24 };
+/** The clean hold, in seconds, before a live band's first release stage. @see data/kernels/fbs.json */
+export const FBS_HOLD_RANGE = { min: 1, max: 300 };
+/** The merge radius, in cents. An integer control. @see data/kernels/fbs.json */
+export const FBS_MERGE_RANGE = { min: 0, max: 600 };
+/** How long a released find's escalation is remembered, in seconds. An integer control. @see data/kernels/fbs.json */
+export const FBS_COOLDOWN_RANGE = { min: 0, max: 7200 };
 /** The travel of ratio, from its table COMP_LIMITS. @see data/kernels/comp.json */
 export const COMP_RATIO_RANGE = { min: 1, max: 20 };
 /** The travel of kneeDb, from its table COMP_LIMITS. @see data/kernels/comp.json */

package/dist/fbs-place.d.ts

@@ -0,0 +1,125 @@
+/** The pools: fixed (ring-out) and live, as OmxFbsPool numbers them. */
+export type FbsPool = 'fixed' | 'live';
+/** The console's FbsAction words, in OmxFbsAction's order. */
+export declare const FBS_ACTIONS: readonly ["notched", "lifted", "pool-full", "re-armed", "easing", "rejected-edge"];
+export type FbsAction = (typeof FBS_ACTIONS)[number];
+/** The hold that never releases. */
+export declare const FBS_HOLD_NEVER: "never";
+/** The CURVE_ORIGINS wire words, by index. */
+export declare const ORIGIN_WORDS: readonly string[];
+/** The CURVE_SHAPES words, by index (the unshaped band is `-`). */
+export declare const SHAPE_WORDS: readonly string[];
+export declare const ORIGIN: {
+    readonly user: number;
+    readonly fbsFixed: number;
+    readonly fbsLive: number;
+};
+export declare const SHAPE: {
+    readonly off: number;
+    readonly bell: number;
+    readonly notch: number;
+};
+/** Slots one placement holds: the band cap's ceiling. */
+export declare const FBS_PLACE_SLOTS: 24;
+/** One report slot's six words, as omx_band_report.h lays them out. */
+export interface BandReport {
+    readonly freqHz: number;
+    readonly depthDb: number;
+    readonly q: number;
+    readonly on: number;
+    readonly origin: number;
+    readonly shape: number;
+}
+/** One confirmed ring: the detector's frequency and depth. */
+export interface FbsFind {
+    readonly freqHz: number;
+    readonly depthDb: number;
+}
+/** One action, with the slot it concerned (-1 for a refusal). */
+export interface FbsEvent {
+    readonly action: FbsAction;
+    readonly freqHz: number;
+    readonly slot: number;
+}
+interface Slot {
+    freqHz: number;
+    gainDb: number;
+    q: number;
+    on: boolean;
+    origin: number;
+    shape: number;
+    seq: number;
+    live: boolean;
+    plantedDb: number;
+    lastRingMs: number;
+    stage: number;
+    dwellStartMs: number | null;
+    reclamps: number;
+    ramp: {
+        step: number;
+        stage: number;
+        fromDb: number;
+        toDb: number;
+        dueMs: number;
+        seq: number;
+    } | null;
+}
+/** 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 declare function fbsGainCap(originIndex: number, db: number): number;
+/** Two readings are the same ringing frequency: within FBS_SAME_RING_HZ or FBS_SAME_RING_SHARE of the higher. */
+export declare function sameRingFreq(aHz: number, bHz: number): boolean;
+/** omx_hrp_cents_between in float: `fabsf(1200 * log2f(a / b))`, 1e9 when either is not positive. */
+export declare function fbsCents(aHz: number, bHz: number): number;
+/** One corrector's placement: the console's FbsCorrector rules over fixed slots. */
+export declare class FbsPlace {
+    pool: FbsPool;
+    holdS: number | typeof FBS_HOLD_NEVER;
+    maxBands: number;
+    notchQ: number;
+    mergeCents: number;
+    cooldownS: number;
+    nowMs: number;
+    memoryDropped: number;
+    protected slots: Slot[];
+    protected memory: Array<{
+        freqHz: number;
+        reclamps: number;
+        releasedMs: number;
+    }>;
+    protected seq: number;
+    protected timerSeq: number;
+    readonly log: FbsEvent[];
+    constructor(pool: FbsPool);
+    /** The arming values, each clamped as the console clamps it. */
+    set(holdS: number | typeof FBS_HOLD_NEVER, maxBands: number, notchQ: number, mergeCents: number, cooldownS: number): void;
+    /** The bands planted, fixed and live together. */
+    count(): number;
+    /** Slot k's six report words. */
+    report(k: number): BandReport;
+    /** The ramp steps due by `nowMs`, earliest first, ties in the order the ramps began. */
+    advance(nowMs: number): void;
+    /** One detector tick: the ramp steps due, a band per newly confirmed ring, then the clean holds. */
+    tick(nowMs: number, snapshotHz: readonly number[], confirmed: readonly FbsFind[]): void;
+    /** One find or another: the same-ring window, or the merge radius in cents (band first, find second). */
+    protected sameRegion(bandHz: number, findHz: number): boolean;
+    /** The pool a find goes to. */
+    protected poolOfFind(): FbsPool;
+    /** The gain cap the placement writes through. */
+    protected capGain(originIndex: number, db: number): number;
+    /** The stage a release eases to after `stage`. */
+    protected nextStage(stage: number): number;
+    /** Free slot k: it reports free and no other slot moves. */
+    protected release(k: number): void;
+    protected emit(action: FbsAction, freqHz: number, slot: number): void;
+    /** Occupied slots in plant order: the console's band order. */
+    protected bySeq(): number[];
+    protected correct(c: FbsFind): void;
+    protected holdSweep(snapshotHz: readonly number[]): void;
+    protected reArm(k: number): void;
+    protected beginStage(k: number, stage: number): void;
+    protected rampStep(k: number): void;
+    protected remember(freqHz: number, reclamps: number): void;
+    protected takeMemory(freqHz: number): number;
+}
+export {};