@openmixer/omx-contract 2.3.0 → 2.5.0

package/README.md

@@ -2,141 +2,61 @@
 <!-- Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com> -->
 # omx-contract
 
-The FreeMixer declarations as data: what a value may be (a travel, a default, a kernel constant, a
-list), as JSON validated by a JSON Schema, rendered by one CLI into
-every language that reads it. Governed by openmixer's
-`docs/design/specs/2026-10-05-omx-contract.md`; 1.0.0 carries the phase-1 items of its §4.1, what
-omx-dsp needs, 1.1.0 adds the flanger, de-esser, phaser, rotary, tremolo and graphic EQ kernels, and
-1.2.0 the chorus, drive, EQ, reverb and pan travels omx-dsp and omx-plugins still kept locally, and
-1.3.0 everything else more than one repository reads: the feedback detector, ring correction and
-RTA constants, the EQ band budget, the choice enums (as the `set` kind), the EQ band counts and the
-one rule that gives a fresh EQ its bands, the measurement rate sets and the bus input cap. What is
-declared here is declared nowhere else: the EQ band budget that 1.2.0 left in openmixer is here too.
-2.0.0 changes how a kernel file is written, not what it declares: every render is the same.
-2.1.0 adds each kernel's ordered controls to the JSON render, and a control's `rearms` flag.
-2.2.0 declares the controls an instance has that were missing: the delay's ping-pong, the drive's auto-gain, stereo
-link and HF roll-off, the compressor's kind and detector oversampling, and an EQ instance's switches, slopes and
-per-band controls (a control's `count`, a use, `of` and `when`, and a default by reference).
-2.3.0 declares the input trim as a kernel, `trim`, whose one control is the console's TRIM_RANGE.
+The FreeMixer declarations as data: what a value may be (a travel, a default, a kernel constant, a list),
+written once as JSON, checked by a JSON Schema and rendered into the languages that read it. The mixer
+engine, the DSP library and the plugins all take their ranges, defaults and constants from here, so a knob
+means the same thing on the console, in a plugin and in a test.
+
+- One declaration per value, one file per group (`data/`), validated against a closed schema.
+- Renders for C (a header), TypeScript and resolved JSON, each held equal to the data by CI.
+- Semantic versioning enforced by a check: a change that narrows or removes a declaration needs a major bump.
+
+## Install
+
+Fedora 44:
 
 ```
-data/                        the declaration, one file per group, edited by hand
-  rates.json  primitives.json  kernels/<kernel>.json
-schema/omx-contract.schema.json   JSON Schema 2020-12: five kinds (scalar, travels, sheet, list, set), closed units, refs, closed derivations
-lib/eq-defaults.mjs          the one default rule for a fresh EQ's bands; the ts and c renders carry it
-bin/omx-contract.mjs         the CLI
-render/                      c.mjs (openmixer's renderer, moved unchanged, under c/), ts.mjs, json.mjs
-include/omxcontract/         the committed c render (what omx-contract-devel installs)
-share/omx-contract/          the committed json render (resolved data)
-test/                        schema, semantic checks, goldens, perturbation, semver, round trip
-tools/proof/round-trip.mjs   the spec §4.4 steps 1 and 2 proof against omx-dsp v0.1.3
-recipes/kernel.recipe.json   what a complete kernel has; recipes/answers/ cites each value in the engine
-tools/omx-new-kernel.mjs     the kernel wizard and importer; tools/kernel-recipe.mjs is `make completeness`
-tools/seed/                  the one-time seed from openmixer's built core (provenance; never run by CI)
-packaging/ debian/           omx-contract-devel (RPM), libomx-contract-dev (deb)
+sudo dnf config-manager addrepo --from-repofile=https://freemixer.github.io/rpm/freemixer.repo
+sudo dnf install omx-contract-devel
 ```
 
-## The kernel file
-
-A kernel file, `data/kernels/<kernel>.json`, holds four sections and nothing else. A sketch, values abridged
-(the tremolo's controls, a gate table, a constant):
-
-```json
-{
-  "$schema": "../../schema/omx-contract.schema.json",
-  "controls": [
-    { "name": "rateHz", "kind": "travel", "global": "TREMOLO_RATE_RANGE", "doc": "…", "travel": { "min": 0.1, "max": 20, "unit": "Hz", "default": 5 } },
-    { "name": "depth", "kind": "travel", "doc": "…", "travel": { "min": 0, "max": 1, "unit": "", "default": 0.5 } },
-    { "name": "mode", "kind": "choice", "doc": "…", "ids": ["tremolo", "pan"], "labels": ["Tremolo", "Pan"] },
-    { "name": "thresholdDb", "kind": "travel", "table": "GATE_LIMITS", "travel": { "min": -80, "max": 0, "unit": "dB" } }
-  ],
-  "tables": { "GATE_LIMITS": { "doc": "…" } },
-  "aggregates": { "TREMOLO_TRAVELS": { "doc": "…", "fields": ["rateHz", "depth"] } },
-  "constants": { "CHORUS_BASE_MS": { "kind": "scalar", "doc": "…", "unit": "ms", "value": 10 } }
-}
+Debian bookworm and trixie (also Raspberry Pi OS and Zynthian):
+
+```
+curl -fsSL https://freemixer.github.io/deb/freemixer.asc | sudo tee /usr/share/keyrings/freemixer.asc >/dev/null
+echo "deb [signed-by=/usr/share/keyrings/freemixer.asc] https://freemixer.github.io/deb/debian/$(. /etc/os-release; echo $VERSION_CODENAME) ./" | sudo tee /etc/apt/sources.list.d/freemixer.list
+sudo apt update && sudo apt install libomx-contract-dev
 ```
 
-- `controls`, in order: a `travel` (one travel) or a `choice` (ordered `ids`, an optional `default` and `labels`).
-  Its item name is `<KERNEL>_<NAME>_RANGE` for a travel and `<KERNEL>_<NAME>S` for a choice (`depth` in
-  tremolo.json is `TREMOLO_DEPTH_RANGE`, `mode` is `TREMOLO_MODES`); `global` names it when it is anything else.
-  A control with a `table` is one field of that table. `"rearms": true` marks a control whose change re-arms the
-  kernel's state, so it is not a smooth parameter (the limiter's `lookaheadMs`: omx-dsp's limiter face re-arms
-  the state and restarts the gain at unity when the look-ahead moves by a frame). It is a boolean, only on a
-  control; it is no item, so the C and TypeScript renders do not carry it.
-- A USE is a control with a `global` and no `travel` or `ids`: it takes the item another control of the kernel
-  declares, of its kind, and adds no item (the EQ's `lpfSlope` takes FILTER_SLOPES, which `hpfSlope` declares).
-- `count` names the item that counts a control the kernel takes once per band: a positive integer scalar
-  (`GEQ_BANDS`), or a sheet whose every variant gives its count as `max` (`EQ_BAND_COUNTS.eq8.max`).
-- `of` and `when` mark a travel that is no control of its own but the travel the control `of` names reaches while
-  the choice `when.control` holds `when.is` (the EQ's `notchQ`: the Q's travel while the band is a notch).
-- A choice's `default` may be `{ "ref": … }` to the scalar that states it; a boolean names the second id of a
-  two-id switch when true, the first when false (the delay's `pingpong` comes up at FX_DELAY_PINGPONG_DEFAULT).
-- `tables`: a travels table whose fields are the controls that name it, in control order (`GATE_LIMITS`).
-- `aggregates`: a travels table whose fields are references to controls declared once above, listed by name.
-- `constants`: scalars, lists and sheets, as items.
-
-`omx-contract validate` refuses any other key, a constant that is a travel or a set, and a kernel file written
-as a flat item map (the 1.x shape). `rates.json` and `primitives.json` stay item maps.
-
-## The JSON render's kernels
-
-Beside `items`, `share/omx-contract/omx-contract.json` carries `kernels`: for every kernel file, its controls in
-the order the file declares them. A consumer reads control order and kinds here, never from a kernel file.
-
-```json
-"kernels": {
-  "limiter": {
-    "controls": [
-      { "name": "ceilingDb", "kind": "travel", "global": "LIMITER_LIMITS", "table": "LIMITER_LIMITS" },
-      { "name": "lookaheadMs", "kind": "travel", "global": "LIMITER_LIMITS", "table": "LIMITER_LIMITS", "rearms": true },
-      { "name": "releaseMs", "kind": "travel", "global": "LIMITER_LIMITS", "table": "LIMITER_LIMITS" }
-    ]
-  },
-  "tremolo": {
-    "controls": [
-      { "name": "rateHz", "kind": "travel", "global": "TREMOLO_RATE_RANGE" },
-      { "name": "mode", "kind": "choice", "global": "TREMOLO_MODES" }
-    ]
-  }
-}
+JavaScript and TypeScript projects (the `ts` render is the main export, the CLI is `omx-contract`):
+
+```
+npm install @openmixer/omx-contract
 ```
 
-- `kind`: `travel` or `choice`.
-- `global`: the item the control's value lives in: `items[global].value` for a travel or a choice, and
-  `items[global].value[name]` for a field of a table, when `table` (the same item) is present.
-- `rearms`: present, and `true`, only on a control that declares it.
-- `count`: present on a control taken once per band, the item that counts it.
-- `when`: on a control another one is `of`, the list `{ control, is, global }`: while `control` holds `is`, the
-  control's travel is `items[global]` (the EQ's `q` reaches EQ_NOTCH_Q_RANGE on a notch). A control that is `of`
-  another is not listed on its own. A use is listed like any control, its `global` the item it takes.
+Every GitHub release also carries the `npm pack` tarball, the RPMs and the debs.
 
-A kernel with no controls (fbs, mixmatrix, rta) is listed with an empty `controls`.
+## Use
 
-## The CLI
+Include the C header and read the constants by name:
 
-```
-npm ci
-node bin/omx-contract.mjs validate                       # schema + semantic checks
-node bin/omx-contract.mjs fmt [--check]                  # the one formatting
-node bin/omx-contract.mjs render --target c|ts|json --out <dir> [--check]
-node bin/omx-contract.mjs semver <previous tag>          # exit 1 if the version bump is short
+```c
+#include <omxcontract/omx_contract_limits.h>
 ```
 
-Exit 0 is a pass, 1 a failure naming file, item and rule, 2 a usage or environment error. A change to
-`data/` is followed by `render --target c --out include`, `render --target json --out
-share/omx-contract` and `render --target ts --out test/golden/ts`; CI holds all three to the data.
+```
+pkg-config --cflags omx-contract
+```
 
-## Consuming it
+Pin one version and build against its renders instead of keeping a copy: the installed package at exactly
+that version (`pkg-config --exact-version=2.5.0 omx-contract`), else the npm tarball, unpacked, and
+`omx-contract render --target c --out build/omx-contract/include`. A kernel's controls and readouts, in their
+order, are in `share/omx-contract/omx-contract.json`; how a declaration is written is in
+[docs/kernel-files.md](docs/kernel-files.md), and what a readout is in [docs/readouts.md](docs/readouts.md).
 
-Pin one version (`omx-contract 2.3.0` in `.github/pins.txt`) and build against its renders, committing
-none: the installed `omx-contract-devel` / `libomx-contract-dev` at exactly that version
-(`pkg-config --exact-version=2.3.0 omx-contract`), else the release's npm tarball, unpacked, and
-`omx-contract render --target c --out build/omx-contract/include`. Include
-`<omxcontract/omx_contract_limits.h>`. A plugin's parameter header is rendered by omx-plugins from its
-declaration, by reference to the kernel travels here (since 1.1.0).
+## Building
 
-The npm package is `@openmixer/omx-contract` on npmjs.org (the `ts` render is its main export); every
-GitHub release also carries the `npm pack` tarball, the RPMs and the debs.
+See [BUILDING.md](BUILDING.md).
 
 ## License
 

package/data/kernels/comp.json

@@ -122,6 +122,32 @@
         "Off",
         "4x"
       ]
+    },
+    {
+      "name": "detectorTopology",
+      "kind": "choice",
+      "global": "DETECTOR_TOPOLOGY",
+      "doc": "Where the compressor's detector listens: `feedforward` hears the slot's input (or its key), `feedback` hears the slot's own pre-make-up output DYN_FB_LOOP_DELAY_SAMPLES late, through one envelope stage, and a keyed slot stays feed-forward (omx-dsp's OMX_DYN_TOPOLOGY_FEEDFORWARD 0 and _FEEDBACK 1, in that order; the set is named for its control, so C spells them OMX_DETECTOR_TOPOLOGY_*). The console's comp row carries it (`detectorTopology`, openmixer's ssl-bus-compressor spec §3a) and comes up `feedforward`, so a zeroed atom is the compressor every slot runs.",
+      "ids": [
+        "feedforward",
+        "feedback"
+      ],
+      "default": "feedforward"
+    }
+  ],
+  "readouts": [
+    {
+      "name": "gainReductionDb",
+      "doc": "The compressor's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to COMP_LIMITS.thresholdDb.min: on a signal at or below 0 dBFS the reduction (x - T)(1 - 1/R) never exceeds -T, and T is at least the threshold's minimum.",
+      "unit": "dB",
+      "min": {
+        "ref": "COMP_LIMITS.thresholdDb.min"
+      },
+      "max": 0,
+      "scale": "linear",
+      "rateHz": {
+        "ref": "READOUT_RATE_HZ"
+      }
     }
   ],
   "tables": {
@@ -145,6 +171,12 @@
           }
         }
       }
+    },
+    "DYN_FB_LOOP_DELAY_SAMPLES": {
+      "kind": "scalar",
+      "doc": "The feedback detector's loop delay, in samples: the output y[n] depends on the gain at n, so the detector can only have heard y[n - 1]. Not a latency: the audio is never delayed by it. omx-dsp's feedback state holds exactly this many output samples per leg.",
+      "unit": "",
+      "value": 1
     }
   }
 }

package/data/kernels/deesser.json

@@ -110,6 +110,21 @@
       ]
     }
   ],
+  "readouts": [
+    {
+      "name": "gainReductionDb",
+      "doc": "The de-esser's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to DEESS_RANGE_RANGE.min: the de-esser reduces by its range at most.",
+      "unit": "dB",
+      "min": {
+        "ref": "DEESS_RANGE_RANGE.min"
+      },
+      "max": 0,
+      "scale": "linear",
+      "rateHz": {
+        "ref": "READOUT_RATE_HZ"
+      }
+    }
+  ],
   "constants": {
     "DEESS_KNEE_DB": {
       "kind": "scalar",

package/data/kernels/gate.json

@@ -128,6 +128,21 @@
       }
     }
   ],
+  "readouts": [
+    {
+      "name": "gainReductionDb",
+      "doc": "The gate's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to GATE_LIMITS.rangeDb.min: the gate attenuates by its range at most.",
+      "unit": "dB",
+      "min": {
+        "ref": "GATE_LIMITS.rangeDb.min"
+      },
+      "max": 0,
+      "scale": "linear",
+      "rateHz": {
+        "ref": "READOUT_RATE_HZ"
+      }
+    }
+  ],
   "tables": {
     "GATE_LIMITS": {
       "doc": "The legal range of each gate field (engineering units). The widget clamps drags to these, `normalizeGate` enforces them, the row's codec refuses by them and the travel sheet publishes them — one source of truth. `rangeDb` reaches GATE_RANGE_FLOOR_DB, shown as \"−∞\" in readouts (a gate fully closed is silence)."

package/data/kernels/limiter.json

@@ -42,6 +42,21 @@
       }
     }
   ],
+  "readouts": [
+    {
+      "name": "gainReductionDb",
+      "doc": "The limiter's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to LIMITER_LIMITS.ceilingDb.min: on a signal at or below 0 dBFS the limiter pulls the peak down to its ceiling at most, and the ceiling is at least its minimum.",
+      "unit": "dB",
+      "min": {
+        "ref": "LIMITER_LIMITS.ceilingDb.min"
+      },
+      "max": 0,
+      "scale": "linear",
+      "rateHz": {
+        "ref": "READOUT_RATE_HZ"
+      }
+    }
+  ],
   "tables": {
     "LIMITER_LIMITS": {
       "doc": "The precision limiter's travels (`2026-09-27-precision-limiter.md` §2), rendered into `omx_contract_limits.h` as `OMX_LIMITER_*` by `harness/contract-limits-gen.mjs`, so `mix_limiter.h` reads them and never restates one (R-094). The ceiling is a TRUE peak in dBFS (the ×4 detector); the look-ahead sets the declared latency; the release is the envelope's time constant on the gain depth."

package/data/primitives.json

@@ -154,5 +154,12 @@
         "scale": "log"
       }
     }
+  },
+  "READOUT_RATE_HZ": {
+    "kind": "scalar",
+    "since": "2.4.0",
+    "doc": "How often a readout's value is published: 50 Hz, one value every 20 ms, the rate a host sends a moving meter at. Every readout reads it as its `rateHz` (docs/readouts.md).",
+    "unit": "Hz",
+    "value": 50
   }
 }

package/dist/ts/omx-contract.d.ts

@@ -254,6 +254,12 @@ export declare const COMP_KINDS: readonly ["comp", "limiter"];
  */
 export declare const DETECTOR_OVERSAMPLINGS: readonly ["auto", "off", "x4"];
 
+/**
+ * Where the compressor's detector listens: `feedforward` hears the slot's input (or its key), `feedback` hears the slot's own pre-make-up output DYN_FB_LOOP_DELAY_SAMPLES late, through one envelope stage, and a keyed slot stays feed-forward (omx-dsp's OMX_DYN_TOPOLOGY_FEEDFORWARD 0 and _FEEDBACK 1, in that order; the set is named for its control, so C spells them OMX_DETECTOR_TOPOLOGY_*). The console's comp row carries it (`detectorTopology`, openmixer's ssl-bus-compressor spec §3a) and comes up `feedforward`, so a zeroed atom is the compressor every slot runs.
+ * @see data/kernels/comp.json
+ */
+export declare const DETECTOR_TOPOLOGY: readonly ["feedforward", "feedback"];
+
 /**
  * The program-dependent release's model constants — the LA-2A's opto cell as DATA (`docs/design/specs/2026-09-26-compressor-models.md` §3b). `chargeMs`/`dischargeMs` are the word's memory constants, shared by every profile; each profile's `fastMs`, `slowMinMs`, `slowMaxMs` and `share` fit the unit's published two-stage recovery. Not operator controls: generated into `omx_contract_limits.h` as `OMX_PROGRAM_RELEASE_*`, which libomxdsp's `omx_env_program_release` reads.
  * @see data/kernels/comp.json
@@ -271,6 +277,12 @@ export declare const PROGRAM_RELEASE: {
   };
 };
 
+/**
+ * The feedback detector's loop delay, in samples: the output y[n] depends on the gain at n, so the detector can only have heard y[n - 1]. Not a latency: the audio is never delayed by it. omx-dsp's feedback state holds exactly this many output samples per leg.
+ * @see data/kernels/comp.json
+ */
+export declare const DYN_FB_LOOP_DELAY_SAMPLES: 1;
+
 /**
  * The detector band's CENTRE, in Hz. Sibilance lives at 5–10 kHz on most voices; 7 kHz with the default width covers 4 950–9 900 Hz, which is where an "s" and a "t" sit on a close vocal mic. The travel is wider than the come-up on both sides on purpose: a bright female vocal wants the band up near 9 kHz and a chesty male one down at 5, and a surface narrower than the row removes reach the console genuinely has (the same reasoning core's `REVERB_CUT_RANGE` records).
  * @see data/kernels/deesser.json
@@ -2020,6 +2032,12 @@ export declare const EQ_CONTINUOUS_TRAVELS: {
   };
 };
 
+/**
+ * How often a readout's value is published: 50 Hz, one value every 20 ms, the rate a host sends a moving meter at. Every readout reads it as its `rateHz` (docs/readouts.md).
+ * @see data/primitives.json
+ */
+export declare const READOUT_RATE_HZ: 50;
+
 /**
  * The standard sample rates (Hz) the desk recognises — the pro-audio superset. One source of truth for the clock controller's `clock.allowed-rates` seed, the force row's validation ceiling and the device-rate probe fallback. What the operator is OFFERED is always the DEVICE's own `supportedRates` (`2026-07-15-clock-rate-honest-force-rate.md`) — this is the ceiling a write is refused by, never a menu.
  * @see data/rates.json
@@ -2053,6 +2071,50 @@ export declare const ORACLE_FLOOR_RATES: readonly [44100, 48000, 96000, 192000];
  */
 export declare const RME_RATES: readonly [32000, 44100, 48000, 64000, 88200, 96000, 128000, 176400, 192000];
 
+/**
+ * Every kernel's readouts, the meters a host draws, each kernel's in its declared order: the position is the
+ * readout's id. Every reference is resolved.
+ * @see docs/readouts.md
+ */
+export declare const READOUTS: {
+  readonly comp: readonly [{
+    readonly name: "gainReductionDb";
+    readonly doc: "The compressor's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to COMP_LIMITS.thresholdDb.min: on a signal at or below 0 dBFS the reduction (x - T)(1 - 1/R) never exceeds -T, and T is at least the threshold's minimum.";
+    readonly unit: "dB";
+    readonly min: -60;
+    readonly max: 0;
+    readonly scale: "linear";
+    readonly rateHz: 50;
+  }];
+  readonly deesser: readonly [{
+    readonly name: "gainReductionDb";
+    readonly doc: "The de-esser's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to DEESS_RANGE_RANGE.min: the de-esser reduces by its range at most.";
+    readonly unit: "dB";
+    readonly min: -24;
+    readonly max: 0;
+    readonly scale: "linear";
+    readonly rateHz: 50;
+  }];
+  readonly gate: readonly [{
+    readonly name: "gainReductionDb";
+    readonly doc: "The gate's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to GATE_LIMITS.rangeDb.min: the gate attenuates by its range at most.";
+    readonly unit: "dB";
+    readonly min: -90;
+    readonly max: 0;
+    readonly scale: "linear";
+    readonly rateHz: 50;
+  }];
+  readonly limiter: readonly [{
+    readonly name: "gainReductionDb";
+    readonly doc: "The limiter's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to LIMITER_LIMITS.ceilingDb.min: on a signal at or below 0 dBFS the limiter pulls the peak down to its ceiling at most, and the ceiling is at least its minimum.";
+    readonly unit: "dB";
+    readonly min: -12;
+    readonly max: 0;
+    readonly scale: "linear";
+    readonly rateHz: 50;
+  }];
+};
+
 /** The default band centres (Hz) of an EQ with `count` bands: THE one rule, for every strip, host and count. */
 export declare function eqDefaultCentres(count: number): number[];
 /** The default band types, by EQ_BAND_TYPES id: a low shelf, bells, a high shelf (a single band is a bell). */

package/dist/ts/omx-contract.js

@@ -264,6 +264,15 @@ export const DETECTOR_OVERSAMPLINGS = [
   "x4"
 ];
 
+/**
+ * Where the compressor's detector listens: `feedforward` hears the slot's input (or its key), `feedback` hears the slot's own pre-make-up output DYN_FB_LOOP_DELAY_SAMPLES late, through one envelope stage, and a keyed slot stays feed-forward (omx-dsp's OMX_DYN_TOPOLOGY_FEEDFORWARD 0 and _FEEDBACK 1, in that order; the set is named for its control, so C spells them OMX_DETECTOR_TOPOLOGY_*). The console's comp row carries it (`detectorTopology`, openmixer's ssl-bus-compressor spec §3a) and comes up `feedforward`, so a zeroed atom is the compressor every slot runs.
+ * @see data/kernels/comp.json
+ */
+export const DETECTOR_TOPOLOGY = [
+  "feedforward",
+  "feedback"
+];
+
 /**
  * The program-dependent release's model constants — the LA-2A's opto cell as DATA (`docs/design/specs/2026-09-26-compressor-models.md` §3b). `chargeMs`/`dischargeMs` are the word's memory constants, shared by every profile; each profile's `fastMs`, `slowMinMs`, `slowMaxMs` and `share` fit the unit's published two-stage recovery. Not operator controls: generated into `omx_contract_limits.h` as `OMX_PROGRAM_RELEASE_*`, which libomxdsp's `omx_env_program_release` reads.
  * @see data/kernels/comp.json
@@ -281,6 +290,12 @@ export const PROGRAM_RELEASE = {
   }
 };
 
+/**
+ * The feedback detector's loop delay, in samples: the output y[n] depends on the gain at n, so the detector can only have heard y[n - 1]. Not a latency: the audio is never delayed by it. omx-dsp's feedback state holds exactly this many output samples per leg.
+ * @see data/kernels/comp.json
+ */
+export const DYN_FB_LOOP_DELAY_SAMPLES = 1;
+
 /**
  * The detector band's CENTRE, in Hz. Sibilance lives at 5–10 kHz on most voices; 7 kHz with the default width covers 4 950–9 900 Hz, which is where an "s" and a "t" sit on a close vocal mic. The travel is wider than the come-up on both sides on purpose: a bright female vocal wants the band up near 9 kHz and a chesty male one down at 5, and a surface narrower than the row removes reach the console genuinely has (the same reasoning core's `REVERB_CUT_RANGE` records).
  * @see data/kernels/deesser.json
@@ -2201,6 +2216,12 @@ export const EQ_CONTINUOUS_TRAVELS = {
   }
 };
 
+/**
+ * How often a readout's value is published: 50 Hz, one value every 20 ms, the rate a host sends a moving meter at. Every readout reads it as its `rateHz` (docs/readouts.md).
+ * @see data/primitives.json
+ */
+export const READOUT_RATE_HZ = 50;
+
 /**
  * The standard sample rates (Hz) the desk recognises — the pro-audio superset. One source of truth for the clock controller's `clock.allowed-rates` seed, the force row's validation ceiling and the device-rate probe fallback. What the operator is OFFERED is always the DEVICE's own `supportedRates` (`2026-07-15-clock-rate-honest-force-rate.md`) — this is the ceiling a write is refused by, never a menu.
  * @see data/rates.json
@@ -2256,6 +2277,58 @@ export const RME_RATES = [
   192000
 ];
 
+/**
+ * Every kernel's readouts, the meters a host draws, each kernel's in its declared order: the position is the
+ * readout's id. Every reference is resolved.
+ * @see docs/readouts.md
+ */
+export const READOUTS = {
+  "comp": [
+    {
+      "name": "gainReductionDb",
+      "doc": "The compressor's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to COMP_LIMITS.thresholdDb.min: on a signal at or below 0 dBFS the reduction (x - T)(1 - 1/R) never exceeds -T, and T is at least the threshold's minimum.",
+      "unit": "dB",
+      "min": -60,
+      "max": 0,
+      "scale": "linear",
+      "rateHz": 50
+    }
+  ],
+  "deesser": [
+    {
+      "name": "gainReductionDb",
+      "doc": "The de-esser's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to DEESS_RANGE_RANGE.min: the de-esser reduces by its range at most.",
+      "unit": "dB",
+      "min": -24,
+      "max": 0,
+      "scale": "linear",
+      "rateHz": 50
+    }
+  ],
+  "gate": [
+    {
+      "name": "gainReductionDb",
+      "doc": "The gate's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to GATE_LIMITS.rangeDb.min: the gate attenuates by its range at most.",
+      "unit": "dB",
+      "min": -90,
+      "max": 0,
+      "scale": "linear",
+      "rateHz": 50
+    }
+  ],
+  "limiter": [
+    {
+      "name": "gainReductionDb",
+      "doc": "The limiter's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to LIMITER_LIMITS.ceilingDb.min: on a signal at or below 0 dBFS the limiter pulls the peak down to its ceiling at most, and the ceiling is at least its minimum.",
+      "unit": "dB",
+      "min": -12,
+      "max": 0,
+      "scale": "linear",
+      "rateHz": 50
+    }
+  ]
+};
+
 /** The declared parameters of the default EQ rule: the four-band set, the preferred series, the band frequency travel, the band gain and Q. */
 const EQ_DEFAULT_RULE = {
   "four": [

package/include/omxcontract/omx_contract_limits.h

@@ -279,6 +279,7 @@
 #define OMX_DRIVE_TRIM_RANGE_STEP 0.1f
 #define OMX_DRIVE_TRIM_RANGE_STEP_DOUBLE 0.1
 #define OMX_DSP_KNOB_REFERENCE_RATE 96000
+#define OMX_DYN_FB_LOOP_DELAY_SAMPLES 1
 #define OMX_EQ_BAND_COUNTS_CHANNEL_DEFAULT 4
 #define OMX_EQ_BAND_COUNTS_CHANNEL_MAX 24
 #define OMX_EQ_BAND_COUNTS_EQ16_DEFAULT 16
@@ -450,6 +451,7 @@
 #define OMX_PROGRAM_RELEASE_PROFILES_OPTO_SLOW_MAX_MS 1100
 #define OMX_PROGRAM_RELEASE_PROFILES_OPTO_SLOW_MIN_MS 110
 #define OMX_PSHR_MIN_DB 10
+#define OMX_READOUT_RATE_HZ 50
 #define OMX_REVERB_DAMPING_RANGE_DEFAULT 0.5f
 #define OMX_REVERB_DAMPING_RANGE_DEFAULT_DOUBLE 0.5
 #define OMX_REVERB_DAMPING_RANGE_MAX 1
@@ -651,6 +653,12 @@ enum omx_detector_oversamplings {
 };
 #define OMX_DETECTOR_OVERSAMPLINGS_COUNT 3u
 #define OMX_DETECTOR_OVERSAMPLINGS_DEFAULT OMX_DETECTOR_OVERSAMPLINGS_AUTO
+enum omx_detector_topology {
+  OMX_DETECTOR_TOPOLOGY_FEEDFORWARD = 0,
+  OMX_DETECTOR_TOPOLOGY_FEEDBACK = 1,
+};
+#define OMX_DETECTOR_TOPOLOGY_COUNT 2u
+#define OMX_DETECTOR_TOPOLOGY_DEFAULT OMX_DETECTOR_TOPOLOGY_FEEDFORWARD
 enum omx_drive_auto_gains {
   OMX_DRIVE_AUTO_GAINS_OFF = 0,
   OMX_DRIVE_AUTO_GAINS_ON = 1,
@@ -750,6 +758,46 @@ enum omx_tremolo_modes {
 #define OMX_TREMOLO_MODES_COUNT 2u
 #define OMX_TREMOLO_MODES_DEFAULT OMX_TREMOLO_MODES_TREMOLO
 
+/* Every kernel's readouts, the meters a host draws (docs/readouts.md): an enum of the readouts at their position,
+ * `OMX_<KERNEL>_READOUT_COUNT`, and per readout its display range (_MIN, _MAX), _RATE_HZ, _SCALE (an OMX_PARAM_SCALES_*
+ * member) and _UNIT. */
+enum omx_comp_readouts {
+  OMX_COMP_READOUT_GAIN_REDUCTION_DB = 0,
+};
+#define OMX_COMP_READOUT_COUNT 1u
+#define OMX_COMP_READOUT_GAIN_REDUCTION_DB_MIN -60.0f
+#define OMX_COMP_READOUT_GAIN_REDUCTION_DB_MAX 0.0f
+#define OMX_COMP_READOUT_GAIN_REDUCTION_DB_RATE_HZ 50
+#define OMX_COMP_READOUT_GAIN_REDUCTION_DB_SCALE OMX_PARAM_SCALES_LINEAR
+#define OMX_COMP_READOUT_GAIN_REDUCTION_DB_UNIT "dB"
+enum omx_deesser_readouts {
+  OMX_DEESSER_READOUT_GAIN_REDUCTION_DB = 0,
+};
+#define OMX_DEESSER_READOUT_COUNT 1u
+#define OMX_DEESSER_READOUT_GAIN_REDUCTION_DB_MIN -24.0f
+#define OMX_DEESSER_READOUT_GAIN_REDUCTION_DB_MAX 0.0f
+#define OMX_DEESSER_READOUT_GAIN_REDUCTION_DB_RATE_HZ 50
+#define OMX_DEESSER_READOUT_GAIN_REDUCTION_DB_SCALE OMX_PARAM_SCALES_LINEAR
+#define OMX_DEESSER_READOUT_GAIN_REDUCTION_DB_UNIT "dB"
+enum omx_gate_readouts {
+  OMX_GATE_READOUT_GAIN_REDUCTION_DB = 0,
+};
+#define OMX_GATE_READOUT_COUNT 1u
+#define OMX_GATE_READOUT_GAIN_REDUCTION_DB_MIN -90.0f
+#define OMX_GATE_READOUT_GAIN_REDUCTION_DB_MAX 0.0f
+#define OMX_GATE_READOUT_GAIN_REDUCTION_DB_RATE_HZ 50
+#define OMX_GATE_READOUT_GAIN_REDUCTION_DB_SCALE OMX_PARAM_SCALES_LINEAR
+#define OMX_GATE_READOUT_GAIN_REDUCTION_DB_UNIT "dB"
+enum omx_limiter_readouts {
+  OMX_LIMITER_READOUT_GAIN_REDUCTION_DB = 0,
+};
+#define OMX_LIMITER_READOUT_COUNT 1u
+#define OMX_LIMITER_READOUT_GAIN_REDUCTION_DB_MIN -12.0f
+#define OMX_LIMITER_READOUT_GAIN_REDUCTION_DB_MAX 0.0f
+#define OMX_LIMITER_READOUT_GAIN_REDUCTION_DB_RATE_HZ 50
+#define OMX_LIMITER_READOUT_GAIN_REDUCTION_DB_SCALE OMX_PARAM_SCALES_LINEAR
+#define OMX_LIMITER_READOUT_GAIN_REDUCTION_DB_UNIT "dB"
+
 /* The default bands of an EQ with `count` bands: THE one rule, for every strip, host and count (omx-contract's
  * lib/eq-defaults.mjs; the ts render exports the same as eqDefaultCentres and eqDefaultTypes). Needs -lm. */
 static inline unsigned omx_eq_default_centres(unsigned count, float *out) {

package/lib/data.mjs

@@ -45,9 +45,12 @@ export function loadData(dir, texts) {
 const snakeOf = (n) => n.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
 const camelOf = (u) => u.toLowerCase().replace(/_([a-z0-9])/g, (_, x) => x.toUpperCase());
 
-/** The four sections of a kernel file, in their order. */
+/** The four sections of a kernel file that declare items, in their order. */
 export const KERNEL_SECTIONS = ['controls', 'tables', 'aggregates', 'constants'];
 
+/** Every top-level key a kernel file may hold, in their order: the four sections and `readouts`, which declares no item. */
+export const KERNEL_KEYS = ['controls', 'readouts', 'tables', 'aggregates', 'constants'];
+
 /** Whether a data file is a kernel file (`kernels/<kernel>.json`), which holds the four sections, never an item map. */
 export const isKernelFile = (rel) => /(^|\/)kernels\/[^/]+\.json$/.test(rel);
 
@@ -261,7 +264,8 @@ const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 /**
  * Resolve every item: `{ name, rel, kind, doc, why?, unit?, c?, shape?, default?, labels?, value }` (default and labels: a set's), where `value` has
  * every `{ref}` and `{derive}` evaluated. The returned map also carries `kernels`, every kernel's ordered controls
- * (kernelControls), which the json render publishes beside the items.
+ * (kernelControls) and, for a kernel that declares them, its ordered `readouts` `{ name, doc, unit, min, max, scale,
+ * rateHz }` with every reference resolved, which the json render publishes beside the items.
  * @throws naming the item: a reference that does not resolve, a cycle, an unknown derivation.
  */
 export function resolveData(data) {
@@ -311,6 +315,13 @@ export function resolveData(data) {
   const out = new Map();
   for (const name of data.items.keys()) out.set(name, resolveItem(name));
   out.kernels = kernelControls(data);
+  for (const f of data.files) {
+    if (!isKernelFile(f.rel) || !Array.isArray(f.doc.readouts)) continue;
+    out.kernels[kernelName(f.rel)].readouts = f.doc.readouts.map((ro) => {
+      const from = `${kernelName(f.rel)}.readouts.${ro.name}`;
+      return { name: ro.name, doc: ro.doc, unit: ro.unit, min: val(ro.min, from), max: val(ro.max, from), scale: ro.scale, rateHz: val(ro.rateHz, from) };
+    });
+  }
   return out;
 }
 

package/lib/fmt.mjs

@@ -4,12 +4,14 @@
  * The one formatting of a data file (spec §3.2): two-space indent, one key per line, keys in schema
  * order, a trailing newline. Names (items, fields, sheet keys) keep the order the author gave them:
  * a travels table's field order is its C block order. A kernel file's sections come in their order (controls,
- * tables, aggregates, constants), its controls in the author's order, each control's keys in schema order.
+ * readouts, tables, aggregates, constants), its controls and readouts in the author's order, each one's keys in
+ * schema order.
  */
 
 const ORDER = {
   control: ['name', 'kind', 'global', 'table', 'rearms', 'since', 'doc', 'why', 'unit', 'ids', 'default', 'labels', 'travel', 'c'],
-  sections: ['controls', 'tables', 'aggregates', 'constants'],
+  sections: ['controls', 'readouts', 'tables', 'aggregates', 'constants'],
+  readout: ['name', 'doc', 'unit', 'min', 'max', 'scale', 'rateHz'],
   item: ['kind', 'since', 'doc', 'why', 'unit', 'value', 'values', 'ids', 'default', 'labels', 'fields', 'travel', 'c'],
   travel: ['min', 'max', 'step', 'unit', 'default', 'defaultFrom', 'scale', 'byKind', 'doc', 'why'],
   c: ['alias', 'render'],
@@ -63,6 +65,13 @@ function control(c) {
   return o;
 }
 
+function readout(r) {
+  if (!isObj(r)) return r;
+  const o = ordered(r, ORDER.readout);
+  for (const k of ['min', 'max', 'rateHz']) if (k in o) o[k] = number(o[k]);
+  return o;
+}
+
 const items = (m) => (isObj(m) ? Object.fromEntries(Object.entries(m).map(([k, v]) => [k, item(v)])) : m);
 
 /** The canonical text of a parsed data file. */
@@ -72,7 +81,9 @@ export function formatDoc(doc) {
   if (ORDER.sections.some((k) => k in doc)) {
     for (const [k, v] of Object.entries(ordered(doc, ORDER.sections))) {
       if (k === '$schema') continue;
-      out[k] = k === 'controls' && Array.isArray(v) ? v.map(control) : ORDER.sections.includes(k) ? items(v) : item(v);
+      if (k === 'controls' && Array.isArray(v)) out[k] = v.map(control);
+      else if (k === 'readouts' && Array.isArray(v)) out[k] = v.map(readout);
+      else out[k] = ORDER.sections.includes(k) ? items(v) : item(v);
     }
   } else {
     for (const [k, v] of Object.entries(doc)) if (k !== '$schema') out[k] = item(v);

package/lib/semver.mjs

@@ -11,6 +11,10 @@
  *   minor  an item, field, sheet leaf, list member or set id added (appended); a travel widened;
  *          a default moved inside its travel; a step changed
  *   patch  doc and why text
+ *
+ * A kernel's readouts (docs/readouts.md): one removed, renamed or moved, or its unit changed, is major (a removal is
+ * minor in the development phase, as an item's is); one appended, or its range, scale or rate changed, is minor; its
+ * doc is patch.
  */
 
 const RANK = { none: 0, patch: 1, minor: 2, major: 3 };
@@ -55,6 +59,29 @@ function leafChanges(at, a, b, say) {
   }
 }
 
+function readoutChanges(prev, next, developmentPhase, say) {
+  for (const k of new Set([...Object.keys(prev), ...Object.keys(next)])) {
+    const a = prev[k]?.readouts ?? [];
+    const b = next[k]?.readouts ?? [];
+    a.forEach((x, i) => {
+      const at = `${k}.readouts.${x.name}`;
+      const j = b.findIndex((y) => y.name === x.name);
+      if (j < 0) {
+        say(developmentPhase ? 'minor' : 'major', at, `readout removed or renamed${developmentPhase ? ' (MINOR in the development phase)' : ''}`);
+        return;
+      }
+      const y = b[j];
+      if (j !== i) say('major', at, `readout moved (id ${i} -> ${j})`);
+      if (x.unit !== y.unit) say('major', at, `unit ${JSON.stringify(x.unit)} -> ${JSON.stringify(y.unit)}`);
+      if (x.min !== y.min || x.max !== y.max) say('minor', at, `range [${x.min}, ${x.max}] -> [${y.min}, ${y.max}]`);
+      if (x.scale !== y.scale) say('minor', at, `scale ${x.scale} -> ${y.scale}`);
+      if (x.rateHz !== y.rateHz) say('minor', at, `rateHz ${x.rateHz} -> ${y.rateHz}`);
+      if (x.doc !== y.doc) say('patch', at, 'doc');
+    });
+    for (const y of b) if (!a.some((x) => x.name === y.name)) say('minor', `${k}.readouts.${y.name}`, 'readout added');
+  }
+}
+
 /** `{ level, changes: [{ level, item, what }] }` from `prev` to `next` (Maps name -> resolved item). */
 export function classify(prev, next, { developmentPhase = DEVELOPMENT_PHASE } = {}) {
   const changes = [];
@@ -107,6 +134,7 @@ export function classify(prev, next, { developmentPhase = DEVELOPMENT_PHASE } =
     }
   }
   for (const name of next.keys()) if (!prev.has(name)) changes.push({ level: 'minor', item: name, what: 'item added' });
+  readoutChanges(prev.kernels ?? {}, next.kernels ?? {}, developmentPhase, (level, item, what) => changes.push({ level, item, what }));
   const level = changes.reduce((m, c) => (RANK[c.level] > RANK[m] ? c.level : m), 'none');
   return { level, changes };
 }

package/lib/validate.mjs

@@ -8,7 +8,7 @@
 import { readFileSync } from 'node:fs';
 import { posix } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
-import { KERNEL_SECTIONS, controlGlobal, entriesOf, isKernelFile, isUse, resolveData } from './data.mjs';
+import { KERNEL_KEYS, KERNEL_SECTIONS, controlGlobal, entriesOf, isKernelFile, isUse, resolveData } from './data.mjs';
 import { eqDefaultBands, eqDefaultParams } from './eq-defaults.mjs';
 import { renderC } from '../render/c.mjs';
 import { renderTs } from '../render/ts.mjs';
@@ -21,18 +21,28 @@ let compiled;
  * `table` declared under `tables`; `rearms` a boolean, and only on a control; a use (a control with a `global` and no
  * travel or ids) naming an item another control of the kernel declares, of its kind; `count` an item name; `of` naming
  * another control of its kind with `when` a { control, is } of a choice of the kernel; an aggregate's fields naming
- * controls; a constant a scalar, a list or a sheet.
+ * controls; a constant a scalar, a list or a sheet; `readouts` a list of readouts, unique by name.
  * A kernel file written as a flat item map (the 1.x shape) is refused as a whole. Any other data file returns [].
  */
 export function shapeProblems(rel, doc) {
   if (!isKernelFile(rel)) return [];
   const sections = KERNEL_SECTIONS;
   const keys = Object.keys(doc).filter((k) => k !== '$schema');
-  if (keys.length && !keys.some((k) => sections.includes(k))) {
+  if (keys.length && !keys.some((k) => KERNEL_KEYS.includes(k))) {
     return [`${rel} is a flat item map (the 1.x shape): a kernel file declares its items under ${sections.join(', ')}`];
   }
   const out = [];
-  for (const k of keys) if (!sections.includes(k)) out.push(`unknown top-level key ${k}: a kernel file holds ${sections.join(', ')}`);
+  for (const k of keys) if (!KERNEL_KEYS.includes(k)) out.push(`unknown top-level key ${k}: a kernel file holds ${KERNEL_KEYS.join(', ')}`);
+  if ('readouts' in doc) {
+    if (!Array.isArray(doc.readouts)) out.push('readouts must be a list');
+    else {
+      const names = new Set();
+      for (const [i, ro] of doc.readouts.entries()) {
+        if (names.has(ro?.name)) out.push(`readouts[${i}]: name ${ro.name} declared twice`);
+        names.add(ro?.name);
+      }
+    }
+  }
   const controls = doc.controls ?? [];
   if (!Array.isArray(controls)) return [...out, 'controls must be a list'];
   const seen = new Set();
@@ -73,12 +83,22 @@ export function shapeProblems(rel, doc) {
   return out;
 }
 
+let ajv;
 /** The compiled schema validator. */
 export function schemaValidator() {
-  if (!compiled) compiled = new Ajv2020({ allErrors: true, strict: true, strictRequired: false, allowUnionTypes: true }).compile(SCHEMA);
+  if (!compiled) {
+    ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false, allowUnionTypes: true });
+    compiled = ajv.compile(SCHEMA);
+  }
   return compiled;
 }
 
+/** The validator of one readout, the schema's `$defs/readout`. */
+export function readoutValidator() {
+  schemaValidator();
+  return ajv.getSchema(`${SCHEMA.$id}#/$defs/readout`);
+}
+
 const constCase = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
 
 /**
@@ -99,6 +119,21 @@ function semanticRules(resolved, say) {
     }
   }
 
+  // A readout's numbers are finite, its range runs upward, its rate is positive and its scale is a PARAM_SCALES id.
+  for (const [k, { readouts }] of Object.entries(resolved.kernels ?? {})) {
+    for (const ro of readouts ?? []) {
+      const rel = `data/kernels/${k}.json`;
+      const at = `${k}.readouts.${ro.name}`;
+      for (const f of ['min', 'max', 'rateHz']) if (typeof ro[f] !== 'number' || !Number.isFinite(ro[f])) say(rel, at, 'finite', `${at}.${f} resolves to ${JSON.stringify(ro[f])}`);
+      if (!(ro.min < ro.max)) say(rel, at, 'readout-range', `${at}: min ${ro.min} is not below max ${ro.max}`);
+      if (!(ro.rateHz > 0)) say(rel, at, 'readout-rate', `${at}: rateHz ${ro.rateHz} is not positive`);
+      if (!(val('PARAM_SCALES') ?? []).includes(ro.scale)) say(rel, at, 'scale', `${at}: scale ${JSON.stringify(ro.scale)} is not an id of PARAM_SCALES`);
+    }
+  }
+  if (resolved.has('READOUTS') && Object.values(resolved.kernels ?? {}).some((k) => k.readouts)) {
+    say(resolved.get('READOUTS').rel, 'READOUTS', 'readouts-name', 'READOUTS is the ts render\'s export of the readouts: no item may take the name');
+  }
+
   // A per-band control's count: a positive integer scalar, or a sheet whose every variant has a positive integer max.
   for (const [k, { controls }] of Object.entries(resolved.kernels ?? {})) {
     for (const c of controls) {
@@ -162,6 +197,13 @@ export function validateData(data) {
     for (const m of shapeProblems(f.rel, f.doc)) say(f.rel, '-', 'shape', m);
     // The schema reads items: a kernel file is checked as the items it expands to, so no rule is lost.
     const items = { $schema: f.doc.$schema, ...Object.fromEntries(entriesOf(f.rel, f.doc)) };
+    if (isKernelFile(f.rel) && Array.isArray(f.doc.readouts)) {
+      const readout = readoutValidator();
+      for (const [i, ro] of f.doc.readouts.entries()) {
+        if (readout(ro)) continue;
+        for (const e of readout.errors) say(f.rel, `readouts[${i}]`, 'schema', `/readouts/${i}${e.instancePath} ${e.message}${e.params?.allowedValues ? ` (${e.params.allowedValues.join(', ')})` : ''}`);
+      }
+    }
     if (!validate(items)) {
       for (const e of validate.errors) {
         const item = e.instancePath.split('/')[1] || '-';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/omx-contract",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "The FreeMixer declarations as data: a JSON Schema, the data, and one CLI that renders them into C, TypeScript and JSON",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/render/c.mjs

@@ -7,7 +7,8 @@
  * declaration, by reference to the items here.
  */
 import {
-  genCoreLimitBlock, genDeclaredListsBlock, genDeclaredRates, genDeclaredScalarsBlock, genLimitBlock, renderContractLimits,
+  cStringLiteral, genCoreLimitBlock, genDeclaredListsBlock, genDeclaredRates, genDeclaredScalarsBlock, genLimitBlock, renderContractLimits,
+  scalarLiteral,
 } from './c/contract-limits-render.mjs';
 import { doors } from './doors.mjs';
 
@@ -55,6 +56,29 @@ function genDeclaredSetsEnums(sets) {
   }).join('\n');
 }
 
+/** A display bound: a float literal, a whole number with its decimal point. */
+const floatLiteral = (n) => `${Number.isInteger(n) ? `${n}.0` : n}f`;
+
+/**
+ * Every kernel's readouts (docs/readouts.md), kernels in file order: an enum of the readouts, each at its position,
+ * `OMX_<KERNEL>_READOUT_COUNT`, and per readout `_MIN`, `_MAX`, `_RATE_HZ`, `_SCALE` and `_UNIT`.
+ */
+function genReadouts(kernels) {
+  return Object.entries(kernels ?? {}).filter(([, k]) => k.readouts?.length).map(([kernel, { readouts }]) => {
+    const K = kernel.toUpperCase();
+    const names = readouts.map((ro) => `OMX_${K}_READOUT_${constCase(ro.name)}`);
+    const lines = [`enum omx_${kernel}_readouts {`, ...names.map((n, i) => `  ${n} = ${i},`), '};', `#define OMX_${K}_READOUT_COUNT ${readouts.length}u`];
+    readouts.forEach((ro, i) => lines.push(
+      `#define ${names[i]}_MIN ${floatLiteral(ro.min)}`,
+      `#define ${names[i]}_MAX ${floatLiteral(ro.max)}`,
+      `#define ${names[i]}_RATE_HZ ${scalarLiteral(ro.rateHz)}`,
+      `#define ${names[i]}_SCALE OMX_PARAM_SCALES_${constCase(ro.scale)}`,
+      `#define ${names[i]}_UNIT ${cStringLiteral(ro.unit)}`,
+    ));
+    return lines.join('\n');
+  }).join('\n');
+}
+
 /**
  * The default band centres of an EQ (lib/eq-defaults.mjs is the rule; this is its C spelling, held
  * equal to it for every count by test/eq-defaults.test.mjs). Writes \`count\` centres to \`out\` and returns
@@ -110,6 +134,7 @@ export function renderLimitsHeader(resolved) {
   const scalars = d.DECLARED_SCALARS.length ? genDeclaredScalarsBlock(d.DECLARED_SCALARS, above) : '';
   const lists = d.DECLARED_LISTS.length ? genDeclaredListsBlock(d.DECLARED_LISTS, defined([tables, aliases, scalars].join('\n'))) : '';
   const sets = d.DECLARED_SET_ITEMS.length ? genDeclaredSetsEnums(d.DECLARED_SET_ITEMS) : '';
+  const readouts = genReadouts(resolved.kernels);
   const centres = resolved.has('EQ_DEFAULT_CENTRES_FOUR_BAND_HZ') ? eqCentresFunction() : '';
   const sections = [
     [tables, `/* Per-parameter numeric travel, one block per \`travels\` table named <PREFIX>_LIMITS:
@@ -121,6 +146,9 @@ export function renderLimitsHeader(resolved) {
     [lists, `/* Every list rendered to C, sorted by list: OMX_<LIST>_COUNT and OMX_<LIST>_INIT { a, b, … }. */`],
     [sets, `/* Every set rendered to C, sorted by set: an enum of the ids (a named id's position, or a numeric id's number), \`OMX_<SET>_COUNT\` and,
  * where the set names a default, \`OMX_<SET>_DEFAULT\`. */`],
+    [readouts, `/* Every kernel's readouts, the meters a host draws (docs/readouts.md): an enum of the readouts at their position,
+ * \`OMX_<KERNEL>_READOUT_COUNT\`, and per readout its display range (_MIN, _MAX), _RATE_HZ, _SCALE (an OMX_PARAM_SCALES_*
+ * member) and _UNIT. */`],
     [centres, `/* The default bands of an EQ with \`count\` bands: THE one rule, for every strip, host and count (omx-contract's
  * lib/eq-defaults.mjs; the ts render exports the same as eqDefaultCentres and eqDefaultTypes). Needs -lm. */`],
   ].filter(([body]) => body);

package/render/json.mjs

@@ -4,7 +4,8 @@
  * The `json` target: the resolved data (every reference and derivation evaluated) for readers in
  * other languages, which need no resolver of their own. Beside the items, `kernels` lists each
  * kernel's controls in their declared order (name, kind, the global each resolves to, the table of a
- * table field, `rearms` when changing it re-arms the kernel's state), so a reader needs no kernel file.
+ * table field, `rearms` when changing it re-arms the kernel's state) and, where it declares any, its readouts, so a
+ * reader needs no kernel file.
  */
 
 /** Every file of the `json` target: `[{ path, text }]`. */

package/render/ts.mjs

@@ -69,11 +69,26 @@ export declare function eqDefaultBands(count: number): { type: string; freqHz: n
   return { js, dts };
 }
 
+/**
+ * Every kernel's readouts as one export, READOUTS: `{ <kernel>: [{ name, doc, unit, min, max, scale, rateHz }] }`,
+ * kernels in file order, absent when no kernel declares one.
+ */
+function readoutsExport(resolved) {
+  const value = Object.fromEntries(Object.entries(resolved.kernels ?? {}).filter(([, k]) => k.readouts?.length).map(([n, k]) => [n, k.readouts]));
+  if (!Object.keys(value).length) return { js: '', dts: '' };
+  const doc = '/**\n * Every kernel\'s readouts, the meters a host draws, each kernel\'s in its declared order: the position is the\n * readout\'s id. Every reference is resolved.\n * @see docs/readouts.md\n */';
+  return {
+    js: `\n${doc}\nexport const READOUTS = ${JSON.stringify(value, null, 2)};\n`,
+    dts: `\n${doc}\nexport declare const READOUTS: ${tsType(value)};\n`,
+  };
+}
+
 /** Every file of the `ts` target: `[{ path, text }]`. */
 export function renderTs(resolved) {
   const items = [...resolved.values()];
   const rule = eqRule(resolved);
-  const js = BANNER + items.map((r) => `\n${docComment(r)}\nexport const ${r.name} = ${JSON.stringify(tsValue(r), null, 2)};\n`).join('') + rule.js;
-  const dts = BANNER + items.map((r) => `\n${docComment(r)}\nexport declare const ${r.name}: ${tsType(tsValue(r))};\n`).join('') + rule.dts;
+  const readouts = readoutsExport(resolved);
+  const js = BANNER + items.map((r) => `\n${docComment(r)}\nexport const ${r.name} = ${JSON.stringify(tsValue(r), null, 2)};\n`).join('') + readouts.js + rule.js;
+  const dts = BANNER + items.map((r) => `\n${docComment(r)}\nexport declare const ${r.name}: ${tsType(tsValue(r))};\n`).join('') + readouts.dts + rule.dts;
   return [{ path: 'omx-contract.js', text: js }, { path: 'omx-contract.d.ts', text: dts }];
 }

package/schema/omx-contract.schema.json

@@ -81,6 +81,21 @@
       "required": ["min", "max"],
       "additionalProperties": false
     },
+    "readout": {
+      "type": "object",
+      "description": "A value a kernel reports while it runs and a host draws: a meter. Declared in a kernel file's `readouts`, in order; its position is its id (docs/readouts.md).",
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z][A-Za-z0-9]*$" },
+        "doc": { "$ref": "#/$defs/text" },
+        "unit": { "$ref": "#/$defs/unit" },
+        "min": { "$ref": "#/$defs/number" },
+        "max": { "$ref": "#/$defs/number" },
+        "scale": { "type": "string", "pattern": "^[a-z]+$", "description": "How a host draws the readout: an id of PARAM_SCALES." },
+        "rateHz": { "$ref": "#/$defs/number" }
+      },
+      "required": ["name", "doc", "unit", "min", "max", "scale", "rateHz"],
+      "additionalProperties": false
+    },
     "sheetValue": {
       "type": "object",
       "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]*$" },

package/share/omx-contract/omx-contract.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/omx-contract",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "items": {
     "PAN_RANGE": {
       "rel": "data/kernels/balance.json",
@@ -299,6 +299,16 @@
         "x4"
       ]
     },
+    "DETECTOR_TOPOLOGY": {
+      "rel": "data/kernels/comp.json",
+      "kind": "set",
+      "doc": "Where the compressor's detector listens: `feedforward` hears the slot's input (or its key), `feedback` hears the slot's own pre-make-up output DYN_FB_LOOP_DELAY_SAMPLES late, through one envelope stage, and a keyed slot stays feed-forward (omx-dsp's OMX_DYN_TOPOLOGY_FEEDFORWARD 0 and _FEEDBACK 1, in that order; the set is named for its control, so C spells them OMX_DETECTOR_TOPOLOGY_*). The console's comp row carries it (`detectorTopology`, openmixer's ssl-bus-compressor spec §3a) and comes up `feedforward`, so a zeroed atom is the compressor every slot runs.",
+      "default": "feedforward",
+      "value": [
+        "feedforward",
+        "feedback"
+      ]
+    },
     "PROGRAM_RELEASE": {
       "rel": "data/kernels/comp.json",
       "kind": "sheet",
@@ -316,6 +326,13 @@
         }
       }
     },
+    "DYN_FB_LOOP_DELAY_SAMPLES": {
+      "rel": "data/kernels/comp.json",
+      "kind": "scalar",
+      "doc": "The feedback detector's loop delay, in samples: the output y[n] depends on the gain at n, so the detector can only have heard y[n - 1]. Not a latency: the audio is never delayed by it. omx-dsp's feedback state holds exactly this many output samples per leg.",
+      "unit": "",
+      "value": 1
+    },
     "DEESS_FREQ_RANGE": {
       "rel": "data/kernels/deesser.json",
       "kind": "travels",
@@ -2453,6 +2470,13 @@
         }
       }
     },
+    "READOUT_RATE_HZ": {
+      "rel": "data/primitives.json",
+      "kind": "scalar",
+      "doc": "How often a readout's value is published: 50 Hz, one value every 20 ms, the rate a host sends a moving meter at. Every readout reads it as its `rateHz` (docs/readouts.md).",
+      "unit": "Hz",
+      "value": 50
+    },
     "STANDARD_SAMPLE_RATES": {
       "rel": "data/rates.json",
       "kind": "list",
@@ -2639,6 +2663,22 @@
           "name": "detectorOversampling",
           "kind": "choice",
           "global": "DETECTOR_OVERSAMPLINGS"
+        },
+        {
+          "name": "detectorTopology",
+          "kind": "choice",
+          "global": "DETECTOR_TOPOLOGY"
+        }
+      ],
+      "readouts": [
+        {
+          "name": "gainReductionDb",
+          "doc": "The compressor's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to COMP_LIMITS.thresholdDb.min: on a signal at or below 0 dBFS the reduction (x - T)(1 - 1/R) never exceeds -T, and T is at least the threshold's minimum.",
+          "unit": "dB",
+          "min": -60,
+          "max": 0,
+          "scale": "linear",
+          "rateHz": 50
         }
       ]
     },
@@ -2684,6 +2724,17 @@
           "kind": "choice",
           "global": "DEESS_MODES"
         }
+      ],
+      "readouts": [
+        {
+          "name": "gainReductionDb",
+          "doc": "The de-esser's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to DEESS_RANGE_RANGE.min: the de-esser reduces by its range at most.",
+          "unit": "dB",
+          "min": -24,
+          "max": 0,
+          "scale": "linear",
+          "rateHz": 50
+        }
       ]
     },
     "delay": {
@@ -2928,6 +2979,17 @@
           "global": "GATE_LIMITS",
           "table": "GATE_LIMITS"
         }
+      ],
+      "readouts": [
+        {
+          "name": "gainReductionDb",
+          "doc": "The gate's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to GATE_LIMITS.rangeDb.min: the gate attenuates by its range at most.",
+          "unit": "dB",
+          "min": -90,
+          "max": 0,
+          "scale": "linear",
+          "rateHz": 50
+        }
       ]
     },
     "geq": {
@@ -2970,6 +3032,17 @@
           "global": "LIMITER_LIMITS",
           "table": "LIMITER_LIMITS"
         }
+      ],
+      "readouts": [
+        {
+          "name": "gainReductionDb",
+          "doc": "The limiter's gain reduction, in dB with CLAP's sign: 0 while it reduces nothing, negative the reduction it applies. The display range runs down to LIMITER_LIMITS.ceilingDb.min: on a signal at or below 0 dBFS the limiter pulls the peak down to its ceiling at most, and the ceiling is at least its minimum.",
+          "unit": "dB",
+          "min": -12,
+          "max": 0,
+          "scale": "linear",
+          "rateHz": 50
+        }
       ]
     },
     "mixmatrix": {