@openmixer/omx-dsp 0.30.1 → 0.32.0

package/src/definitions.ts

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
-// GENERATED by ts/tools/definitions.mjs from omx-dsp data/kernels/ - do not edit.
+// GENERATED by ts/tools/definitions.mjs from omx-dsp data/ - do not edit.
 
 /** The RTA's target bin resolution — generated into `omx_contract_limits.h` as `OMX_RTA_TARGET_BIN_HZ`, which `mix_dsp.h` reads; the engine's conformance test reads it back from the header. (Hz) @see data/kernels/rta.json */
 export const RTA_TARGET_BIN_HZ = 5.9;
@@ -20,8 +20,162 @@ export const LOWPASS_HANDOVER = {
   hiAtPeakQ: 0.8,
 } as const;
 
+/** 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,
+} as const;
+
+/** 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'] as const;
+
+/** 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 */
+export const CURVE_FAMILIES = ['eq', 'dynamics', 'limiter', 'gate', 'deesser'] as const;
+
+/** The roles of a panel description a curve request reads, by the description's role word (the wire spells each id in snake case: `band_freq`, `knee_start`). The EQ's indexed band roles and head filters, and the gain computer's terms. A term of any other role is no term of the curve. @see data/primitives/curve.json */
+export const CURVE_ROLES = ['bandType', 'bandFreq', 'bandGain', 'bandQ', 'bandOn', 'hpfFreq', 'hpfSlope', 'hpfOn', 'lpfFreq', 'lpfSlope', 'lpfOn', 'threshold', 'ratio', 'knee', 'makeup', 'range', 'kneeStart', 'kneeEnd'] as const;
+
+/** 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'] as const;
+
+/** 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'] as const;
+
+/** 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'] as const;
+
+/** 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'] as const;
+
+/** 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;
+
+/** A curve's default extents, where a request gives none: an eq_response from `freqMinHz` to the lower of `freqMaxHz` and `nyquistFraction` of Nyquist, each band's dB floored at `eqFloorDb` so a notch's null stays finite (the console's EQ draws to -120 dB); a transfer_curve's input from `levelMinDb` to `levelMaxDb`. Hz and dB. @see data/primitives/curve.json */
+export const CURVE_EXTENTS = {
+  freqMinHz: 20,
+  freqMaxHz: 20000,
+  nyquistFraction: 0.999,
+  eqFloorDb: -120,
+  levelMinDb: -80,
+  levelMaxDb: 0,
+} as const;
+
+/** The floor of the linear-to-decibel conversions (`omx_lin_to_db`, `omx_lin_to_db_poly`): an amplitude below `lin` reads as `lin`, so silence is `db` dB, never -inf or NaN. `db` is `20·log10(lin)`. A design constant, not a control. @see data/primitives/lin-to-db-floor.json */
+export const LIN_TO_DB_FLOOR = {
+  lin: 1e-9,
+  db: -180,
+} as const;
+
+/** 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,
+} as const;
+
+/** 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'] as const;
+
+/** 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'] as const;
+
+/** 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'] as const;
+
+/** The labels of METER_UNITS, in its order. @see data/primitives/meter.json */
+export const METER_UNITS_LABELS = ['dBFS', 'dBTP', 'LUFS', 'LU', 'dB'] as const;
+
+/** 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'] 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;
+
+/** 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 } as const;
+
+/** The frequency band a parametric band can be dragged across. @see data/kernels/eq.json */
+export const EQ_FREQ_RANGE = { min: 20, max: 20000 } as const;
+
+/** 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 } as const;
+
+/** 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 } as const;
+
+/** The merge radius, in cents. An integer control. @see data/kernels/fbs.json */
+export const FBS_MERGE_RANGE = { min: 0, max: 600 } as const;
+
+/** 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 } as const;
+
+/** The travel of ratio, from its table COMP_LIMITS. @see data/kernels/comp.json */
+export const COMP_RATIO_RANGE = { min: 1, max: 20 } as const;
+
+/** The travel of kneeDb, from its table COMP_LIMITS. @see data/kernels/comp.json */
+export const COMP_KNEE_DB_RANGE = { min: 0, max: 24 } as const;
+
+/** The travel of ratio, from its table GATE_LIMITS. @see data/kernels/gate.json */
+export const GATE_RATIO_RANGE = { min: 1, max: 100 } as const;
+
+/** The travel of rangeDb, from its table GATE_LIMITS. @see data/kernels/gate.json */
+export const GATE_RANGE_DB_RANGE = { min: -90, max: 0 } as const;

package/src/fbs-place.ts

@@ -0,0 +1,367 @@
+// 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 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 const FBS_ACTIONS = ['notched', 'lifted', 'pool-full', 're-armed', 'easing', 'rejected-edge'] as const;
+export type FbsAction = (typeof FBS_ACTIONS)[number];
+
+/** The hold that never releases. */
+export const FBS_HOLD_NEVER = 'never' as const;
+
+/** The CURVE_ORIGINS wire words, by index. */
+export const ORIGIN_WORDS: readonly string[] = 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: readonly string[] = CURVE_SHAPES.map((id) => (id === 'unshaped' ? '-' : id));
+
+const origin = (word: string): number => ORIGIN_WORDS.indexOf(word);
+const shape = (word: string): number => SHAPE_WORDS.indexOf(word);
+export const ORIGIN = { user: origin('user'), fbsFixed: origin('fbs-fixed'), fbsLive: origin('fbs-live') } as const;
+export const SHAPE = { off: shape('off'), bell: shape('bell'), notch: shape('notch') } as const;
+
+/** Slots one placement holds: the band cap's ceiling. */
+export const FBS_PLACE_SLOTS = FBS_BANDS_RANGE.max;
+
+/** 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;
+}
+
+const freeSlot = (): Slot => ({
+  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: number, lo: number, hi: number): number => (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: number, db: number): number {
+  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: number, bHz: number): boolean {
+  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: number, bHz: number): number {
+  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: number): number => Math.round(x);
+
+/** One corrector's placement: the console's FbsCorrector rules over fixed slots. */
+export class FbsPlace {
+  pool: FbsPool;
+  holdS: number | typeof FBS_HOLD_NEVER = FBS_DEFAULT_HOLD_SECONDS;
+  maxBands: number = FBS_DEFAULT_MAX_AUTO_BANDS;
+  notchQ: number = FBS_DEFAULT_NOTCH_Q;
+  mergeCents: number = FBS_DEFAULT_MERGE_CENTS;
+  cooldownS: number = FBS_DEFAULT_COOLDOWN_SECONDS;
+  nowMs = 0;
+  memoryDropped = 0;
+  protected slots: Slot[] = Array.from({ length: FBS_PLACE_SLOTS }, freeSlot);
+  protected memory: Array<{ freqHz: number; reclamps: number; releasedMs: number }> = [];
+  protected seq = 0;
+  protected timerSeq = 0;
+  readonly log: FbsEvent[] = [];
+
+  constructor(pool: FbsPool) {
+    this.pool = pool;
+  }
+
+  /** 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 {
+    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(): number {
+    return this.slots.filter((s) => s.origin !== ORIGIN.user).length;
+  }
+
+  /** Slot k's six report words. */
+  report(k: number): BandReport {
+    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: number): void {
+    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: number, snapshotHz: readonly number[], confirmed: readonly FbsFind[]): void {
+    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). */
+  protected sameRegion(bandHz: number, findHz: number): boolean {
+    return sameRingFreq(bandHz, findHz) || fbsCents(bandHz, findHz) <= this.mergeCents;
+  }
+
+  /** The pool a find goes to. */
+  protected poolOfFind(): FbsPool {
+    return this.pool;
+  }
+
+  /** The gain cap the placement writes through. */
+  protected capGain(originIndex: number, db: number): number {
+    return fbsGainCap(originIndex, db);
+  }
+
+  /** The stage a release eases to after `stage`. */
+  protected nextStage(stage: number): number {
+    return stage + 1;
+  }
+
+  /** Free slot k: it reports free and no other slot moves. */
+  protected release(k: number): void {
+    this.slots[k] = freeSlot();
+  }
+
+  protected emit(action: FbsAction, freqHz: number, slot: number): void {
+    this.log.push({ action, freqHz, slot });
+  }
+
+  /** Occupied slots in plant order: the console's band order. */
+  protected bySeq(): number[] {
+    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);
+  }
+
+  protected correct(c: FbsFind): void {
+    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);
+  }
+
+  protected holdSweep(snapshotHz: readonly number[]): void {
+    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));
+      }
+    }
+  }
+
+  protected reArm(k: number): void {
+    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);
+  }
+
+  protected beginStage(k: number, stage: number): void {
+    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 };
+  }
+
+  protected rampStep(k: number): void {
+    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);
+  }
+
+  protected remember(freqHz: number, reclamps: number): void {
+    if (this.memory.length >= FBS_RING_MEMORY_SLOTS) {
+      this.memory.shift();
+      this.memoryDropped++;
+    }
+    this.memory.push({ freqHz, reclamps, releasedMs: this.nowMs });
+  }
+
+  protected takeMemory(freqHz: number): number {
+    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/src/gaincomp.ts

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The gain computer twins: omx_gaincomp_db, omx_gaincomp_db_shifted and omx_gate_knee (omx_gaincomp.h, omx_gate.h),
+ * the static characteristic a dynamics curve draws. The kernel is float; each step here is rounded to float by
+ * Math.fround as the kernel rounds it (every operation is one IEEE single operation, and a double result rounded
+ * once to single is the single result for +, -, *, / and sqrt), so the twin is the kernel's value, bit for bit,
+ * where the kernel is built without contraction (-ffp-contract=off, as omxdsp.pc says). Pinned by
+ * test/agreement.test.mjs.
+ */
+
+const f = Math.fround;
+
+/** The gain computer's mode: act ABOVE the threshold (comp, limiter), BELOW it (gate, expander), or raise the
+ *  signal below it (UPWARD). omx_gaincomp.h's OMX_DYN_ABOVE, OMX_DYN_BELOW and OMX_DYN_UPWARD. */
+export type GaincompMode = 'above' | 'below' | 'upward';
+
+/** The gain computer's parameters, omx_gaincomp_params: each value is narrowed to float as the kernel stores it. */
+export interface GaincompParams {
+  readonly mode: GaincompMode;
+  /** The threshold, dB. */
+  readonly threshDb: number;
+  /** The ratio, at least the mode's minimum. */
+  readonly ratio: number;
+  /** The knee width, dB, not negative; 0 is a hard knee. */
+  readonly kneeDb: number;
+  /** BELOW: the attenuation floor, dB, at most 0. UPWARD: the largest boost, dB. Not read in ABOVE. */
+  readonly rangeDb: number;
+}
+
+/**
+ * The static gain, dB, at detector level `levelDb`: the twin of omx_gaincomp_db (its per-sample form).
+ * @param p The parameters.
+ * @param levelDb The detector level, dB; finite.
+ */
+export function gaincompDb(p: GaincompParams, levelDb: number): number {
+  const thresh = f(p.threshDb), ratio = f(p.ratio), knee = f(p.kneeDb), range = f(p.rangeDb);
+  const x = f(f(levelDb) - thresh);
+  const half = f(0.5 * knee);
+  const soft = knee > 0;
+  const k2 = soft ? f(2 * knee) : 1;
+  const eb = f(x - half);
+  const kb = f(f(f(f(1 - ratio) * eb) * eb) / k2);
+  let gb = soft && x > -half ? kb : f(f(ratio - 1) * x);
+  gb = x >= half ? 0 : gb;
+  gb = gb < range ? range : gb;
+  const slope = f(f(1 / ratio) - 1);
+  const ea = f(x + half);
+  const ka = f(f(f(slope * ea) * ea) / k2);
+  let ga = soft && x < half ? ka : f(slope * x);
+  ga = x <= -half ? 0 : ga;
+  const eu = f(half - x);
+  const ku = f(f(f(slope * eu) * eu) / k2);
+  let gu = soft && -x < half ? ku : f(slope * -x);
+  gu = -x <= -half ? 0 : -gu;
+  gu = gu > range ? range : gu;
+  return p.mode === 'below' ? gb : p.mode === 'upward' ? gu : ga;
+}
+
+/** The gate's off-centre knee, omx_gaincomp_knee_shifted: the quadratic Bezier between the expander's line and
+ *  0 dB at `x`, for `xl < x < xh`, every value already a float. */
+function kneeShifted(ratio: number, xl: number, xh: number, x: number): number {
+  const a = f(xl + xh), b = f(-2 * xl), d = f(x - xl);
+  const disc0 = f(f(b * b) + f(f(4 * a) * d));
+  const disc = disc0 > 0 ? disc0 : 0;
+  const den0 = f(b + f(Math.sqrt(disc)));
+  const den = den0 > 0 ? den0 : 1;
+  const u = f(f(2 * d) / den);
+  const w = f(1 - u);
+  return f(f(f(w * w) * f(ratio - 1)) * xl);
+}
+
+/**
+ * The BELOW static gain, dB, with the knee's centre moved `shiftDb` off the threshold: the twin of
+ * omx_gaincomp_db_shifted. A shift of 0 is {@link gaincompDb} itself.
+ * @param p The parameters, `mode` 'below'.
+ * @param shiftDb The knee centre's offset from the threshold, dB, inside half the knee.
+ * @param levelDb The detector level, dB; finite.
+ */
+export function gaincompDbShifted(p: GaincompParams, shiftDb: number, levelDb: number): number {
+  const shift = f(shiftDb);
+  if (shift === 0) return gaincompDb(p, levelDb);
+  const thresh = f(p.threshDb), ratio = f(p.ratio), range = f(p.rangeDb);
+  const half = f(0.5 * f(p.kneeDb));
+  const x = f(f(levelDb) - thresh);
+  const xl = f(shift - half), xh = f(shift + half);
+  let g: number;
+  if (x <= xl) g = f(f(ratio - 1) * x);
+  else if (x >= xh) g = 0;
+  else g = kneeShifted(ratio, xl, xh, x);
+  return g < range ? range : g;
+}
+
+/**
+ * The knee range of a gate as the kernel resolves it, omx_gate_knee: the width of the range and its centre's offset
+ * from the threshold, held inside half the width; equal ends are the hard knee wherever they sit.
+ * @param threshDb The threshold, dB.
+ * @param kneeStartDb One end of the range, dB.
+ * @param kneeEndDb The other end, dB.
+ */
+export function gateKnee(threshDb: number, kneeStartDb: number, kneeEndDb: number): { kneeDb: number; shiftDb: number } {
+  const s = f(kneeStartDb), e = f(kneeEndDb);
+  const lo = s < e ? s : e, hi = s < e ? e : s;
+  const width = f(hi - lo);
+  const half = f(0.5 * width);
+  let shift = width > 0 ? f(f(lo + half) - f(threshDb)) : 0;
+  shift = shift < -half ? -half : shift > half ? half : shift;
+  return { kneeDb: width, shiftDb: shift };
+}