@openmixer/omx-contract 2.1.0 → 2.2.0

package/README.md

@@ -14,6 +14,9 @@ one rule that gives a fresh EQ its bands, the measurement rate sets and the bus
 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).
 
 ```
 data/                        the declaration, one file per group, edited by hand
@@ -59,6 +62,14 @@ A kernel file, `data/kernels/<kernel>.json`, holds four sections and nothing els
   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.
@@ -93,6 +104,10 @@ the order the file declares them. A consumer reads control order and kinds here,
 - `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.
 
 A kernel with no controls (fbs, mixmatrix, rta) is listed with an empty `controls`.
 
@@ -112,9 +127,9 @@ share/omx-contract` and `render --target ts --out test/golden/ts`; CI holds all
 
 ## Consuming it
 
-Pin one version (`omx-contract 2.1.0` in `.github/pins.txt`) and build against its renders, committing
+Pin one version (`omx-contract 2.2.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.1.0 omx-contract`), else the release's npm tarball, unpacked, and
+(`pkg-config --exact-version=2.2.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).

package/data/kernels/comp.json

@@ -91,6 +91,37 @@
         "default": 100,
         "defaultFrom": "desk"
       }
+    },
+    {
+      "name": "kind",
+      "kind": "choice",
+      "doc": "The compressor's character, which picks its detector: `comp` runs the RMS detector, `limiter` the peak detector. The console's comp row carries it (`CompState.kind`, `COMP_KINDS`) and comes up as `comp`.",
+      "ids": [
+        "comp",
+        "limiter"
+      ],
+      "default": "comp",
+      "labels": [
+        "Compressor",
+        "Limiter"
+      ]
+    },
+    {
+      "name": "detectorOversampling",
+      "kind": "choice",
+      "global": "DETECTOR_OVERSAMPLINGS",
+      "doc": "The compressor's detector oversampling: `auto` runs the control path at 4x only while the attack is faster than DETECTOR_OVERSAMPLE_AUTO_MS, `off` never, `x4` always (omx-dsp's OMX_DYN_OVS_AUTO, _OFF and _X4, in that order). The console's comp row carries it as the operator's choice (`CompState.detectorOversampling`, spelled auto, off, 4x) and comes up `auto`.",
+      "ids": [
+        "auto",
+        "off",
+        "x4"
+      ],
+      "default": "auto",
+      "labels": [
+        "Auto",
+        "Off",
+        "4x"
+      ]
     }
   ],
   "tables": {

package/data/kernels/delay.json

@@ -63,6 +63,22 @@
           "fxReturn": 1
         }
       }
+    },
+    {
+      "name": "pingpong",
+      "kind": "choice",
+      "doc": "The FX delay's PING-PONG switch: on cross-feeds the two legs' feedback, so each leg's repeats come from the other leg's damped tap and the echoes bounce L<->R (`omx_delay.h`'s `struct omx_fx_delay.pingpong`, read where the feedback is formed). A live control on the console's delay row (`DelayState.pingpong`) and on the omx-delay plugin. Its come-up value is FX_DELAY_PINGPONG_DEFAULT, by reference, so the default keeps one home.",
+      "ids": [
+        "off",
+        "on"
+      ],
+      "default": {
+        "ref": "FX_DELAY_PINGPONG_DEFAULT"
+      },
+      "labels": [
+        "Off",
+        "On"
+      ]
     }
   ],
   "constants": {

package/data/kernels/drive.json

@@ -117,6 +117,50 @@
         "high",
         "tilt"
       ]
+    },
+    {
+      "name": "autoGain",
+      "kind": "choice",
+      "doc": "The drive's AUTO-GAIN switch: on, the stage measures its own level change and matches it out (`omx_drive.h`'s `struct omx_drive.auto_gain`, drive-stage spec §4d), so turning the drive up adds colour rather than loudness. A field of the console's drive row (`DriveState.autoGain`), on at come-up there and in omx-dsp's drive face.",
+      "ids": [
+        "off",
+        "on"
+      ],
+      "default": "on",
+      "labels": [
+        "Off",
+        "On"
+      ]
+    },
+    {
+      "name": "stereoLink",
+      "kind": "choice",
+      "doc": "The drive's STEREO LINK switch: on, ONE auto-gain path is driven by both legs' summed energy, so the image cannot shift under the level match; off, each leg matches its own (`omx_drive.h`'s `struct omx_drive.stereo_link`, spec §4e). A field of the console's drive row (`DriveState.stereoLink`), on at come-up there and in omx-dsp's drive face.",
+      "ids": [
+        "off",
+        "on"
+      ],
+      "default": "on",
+      "labels": [
+        "Off",
+        "On"
+      ]
+    },
+    {
+      "name": "hfRolloff",
+      "kind": "choice",
+      "doc": "The drive's post-curve HIGH-FREQUENCY ROLL-OFF corner, in Hz: the id is the corner, and 0 names no roll-off (the section does not run: `omx_drive.h`'s `struct omx_drive.hf_on` is 0). The console's drive row offers off, 12000 and 16000 (`DriveState.hfRolloff`, `DRIVE_HF_ROLLOFFS`) and comes up off, as omx-dsp's drive face does.",
+      "ids": [
+        0,
+        12000,
+        16000
+      ],
+      "default": 0,
+      "labels": [
+        "Off",
+        "12 kHz",
+        "16 kHz"
+      ]
     }
   ],
   "constants": {

package/data/kernels/eq.json

@@ -2,48 +2,18 @@
   "$schema": "../../schema/omx-contract.schema.json",
   "controls": [
     {
-      "name": "freq",
-      "kind": "travel",
-      "doc": "The frequency band a parametric band can be dragged across.",
-      "travel": {
-        "min": 20,
-        "max": 20000,
-        "step": 10,
-        "unit": "Hz"
-      }
-    },
-    {
-      "name": "gain",
-      "kind": "travel",
-      "doc": "The parametric-band gain travel, in dB. The ± scalar `clampEqGain` enforces is READ off this (`core/src/eq.ts` derives `EQ_GAIN_LIMIT_DB` from `max`), so the bound is stated once and a surface cannot draw a wider knob than the clamp will honour.",
-      "travel": {
-        "min": -15,
-        "max": 15,
-        "step": 0.5,
-        "unit": "dB"
-      }
-    },
-    {
-      "name": "q",
-      "kind": "travel",
-      "doc": "The Q (resonance) extent of a parametric band.",
-      "travel": {
-        "min": 0.3,
-        "max": 8,
-        "step": 0.1,
-        "unit": ""
-      }
-    },
-    {
-      "name": "notchQ",
-      "kind": "travel",
-      "doc": "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.",
-      "travel": {
-        "min": 0.3,
-        "max": 116,
-        "step": 1,
-        "unit": ""
-      }
+      "name": "hpfOn",
+      "kind": "choice",
+      "doc": "The HPF's switch: off, the filter is not in the EQ's bank at all; on, its one or two Butterworth sections run after the bands. It comes up off, on the console's channel EQ and in omx-dsp's EQ face (see EQ_PASS_FILTER_DEFAULTS).",
+      "ids": [
+        "off",
+        "on"
+      ],
+      "default": "off",
+      "labels": [
+        "Off",
+        "On"
+      ]
     },
     {
       "name": "hpfFreq",
@@ -57,6 +27,31 @@
         "unit": "Hz"
       }
     },
+    {
+      "name": "hpfSlope",
+      "kind": "choice",
+      "global": "FILTER_SLOPES",
+      "doc": "The pass-filter slopes the EQ offers, in dB per octave: the HPF's slope, and by use the LPF's. The id is the slope: 12 is one maximally flat section, 24 the two-section Butterworth.",
+      "ids": [
+        12,
+        24
+      ],
+      "default": 12
+    },
+    {
+      "name": "lpfOn",
+      "kind": "choice",
+      "doc": "The LPF's switch: off, the filter is not in the EQ's bank at all; on, its one or two Butterworth sections run after the bands and the HPF. It comes up off, on the console's channel EQ and in omx-dsp's EQ face (see EQ_PASS_FILTER_DEFAULTS).",
+      "ids": [
+        "off",
+        "on"
+      ],
+      "default": "off",
+      "labels": [
+        "Off",
+        "On"
+      ]
+    },
     {
       "name": "lpfFreq",
       "kind": "travel",
@@ -69,6 +64,11 @@
         "unit": "Hz"
       }
     },
+    {
+      "name": "lpfSlope",
+      "kind": "choice",
+      "global": "FILTER_SLOPES"
+    },
     {
       "name": "bandType",
       "kind": "choice",
@@ -89,18 +89,74 @@
         "Notch",
         "All-pass 1st",
         "All-pass 2nd"
-      ]
+      ],
+      "count": "EQ_BAND_COUNTS"
     },
     {
-      "name": "filterSlope",
+      "name": "freq",
+      "kind": "travel",
+      "doc": "The frequency band a parametric band can be dragged across.",
+      "travel": {
+        "min": 20,
+        "max": 20000,
+        "step": 10,
+        "unit": "Hz"
+      },
+      "count": "EQ_BAND_COUNTS"
+    },
+    {
+      "name": "gain",
+      "kind": "travel",
+      "doc": "The parametric-band gain travel, in dB. The ± scalar `clampEqGain` enforces is READ off this (`core/src/eq.ts` derives `EQ_GAIN_LIMIT_DB` from `max`), so the bound is stated once and a surface cannot draw a wider knob than the clamp will honour.",
+      "travel": {
+        "min": -15,
+        "max": 15,
+        "step": 0.5,
+        "unit": "dB"
+      },
+      "count": "EQ_BAND_COUNTS"
+    },
+    {
+      "name": "q",
+      "kind": "travel",
+      "doc": "The Q (resonance) extent of a parametric band.",
+      "travel": {
+        "min": 0.3,
+        "max": 8,
+        "step": 0.1,
+        "unit": ""
+      },
+      "count": "EQ_BAND_COUNTS"
+    },
+    {
+      "name": "notchQ",
+      "kind": "travel",
+      "doc": "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.",
+      "travel": {
+        "min": 0.3,
+        "max": 116,
+        "step": 1,
+        "unit": ""
+      },
+      "of": "q",
+      "when": {
+        "control": "bandType",
+        "is": "notch"
+      }
+    },
+    {
+      "name": "bandOn",
       "kind": "choice",
-      "global": "FILTER_SLOPES",
-      "doc": "The pass-filter slopes the EQ offers, in dB per octave. The id is the slope: 12 is one maximally flat section, 24 the two-section Butterworth.",
+      "doc": "A band's switch. Off, the band is not in the EQ's bank (the slots close up); on, it runs, parked when it is a gain-carrying shape at 0 dB. No come-up value is declared, because the strips differ: the console's channel EQ brings its default bands up on, an omx-eq plugin brings every band up off so a racked instance is a wire.",
       "ids": [
-        12,
-        24
+        "off",
+        "on"
       ],
-      "default": 12
+      "labels": [
+        "Off",
+        "On"
+      ],
+      "count": "EQ_BAND_COUNTS"
     }
   ],
   "constants": {

package/data/kernels/geq.json

@@ -12,7 +12,8 @@
         "unit": "dB",
         "default": 0,
         "defaultFrom": "desk"
-      }
+      },
+      "count": "GEQ_BANDS"
     }
   ],
   "constants": {

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

@@ -242,6 +242,18 @@ export declare const COMP_LIMITS: {
   };
 };
 
+/**
+ * The compressor's character, which picks its detector: `comp` runs the RMS detector, `limiter` the peak detector. The console's comp row carries it (`CompState.kind`, `COMP_KINDS`) and comes up as `comp`.
+ * @see data/kernels/comp.json
+ */
+export declare const COMP_KINDS: readonly ["comp", "limiter"];
+
+/**
+ * The compressor's detector oversampling: `auto` runs the control path at 4x only while the attack is faster than DETECTOR_OVERSAMPLE_AUTO_MS, `off` never, `x4` always (omx-dsp's OMX_DYN_OVS_AUTO, _OFF and _X4, in that order). The console's comp row carries it as the operator's choice (`CompState.detectorOversampling`, spelled auto, off, 4x) and comes up `auto`.
+ * @see data/kernels/comp.json
+ */
+export declare const DETECTOR_OVERSAMPLINGS: readonly ["auto", "off", "x4"];
+
 /**
  * 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
@@ -417,6 +429,12 @@ export declare const DELAY_MIX_RANGE: {
   };
 };
 
+/**
+ * The FX delay's PING-PONG switch: on cross-feeds the two legs' feedback, so each leg's repeats come from the other leg's damped tap and the echoes bounce L<->R (`omx_delay.h`'s `struct omx_fx_delay.pingpong`, read where the feedback is formed). A live control on the console's delay row (`DelayState.pingpong`) and on the omx-delay plugin. Its come-up value is FX_DELAY_PINGPONG_DEFAULT, by reference, so the default keeps one home.
+ * @see data/kernels/delay.json
+ */
+export declare const DELAY_PINGPONGS: readonly ["off", "on"];
+
 /**
  * The FX delay's PING-PONG come-up value — a toggle, so it has no travel, only this. Declared here rather than as a literal in the server's `DEFAULT_DELAY_STATE` (which now reads it) so the DPF plugin generator (`packages/omx-plugins/tools/params-gen.mjs`, `2026-09-25-omx-plugins-dpf.md` §3a) reads the same fact the desk seeds a fresh strip with.
  * @see data/kernels/delay.json
@@ -500,12 +518,76 @@ export declare const DRIVE_CURVES: readonly ["soft", "tape", "tube", "exciter"];
  */
 export declare const DRIVE_BANDS: readonly ["full", "low", "high", "tilt"];
 
+/**
+ * The drive's AUTO-GAIN switch: on, the stage measures its own level change and matches it out (`omx_drive.h`'s `struct omx_drive.auto_gain`, drive-stage spec §4d), so turning the drive up adds colour rather than loudness. A field of the console's drive row (`DriveState.autoGain`), on at come-up there and in omx-dsp's drive face.
+ * @see data/kernels/drive.json
+ */
+export declare const DRIVE_AUTO_GAINS: readonly ["off", "on"];
+
+/**
+ * The drive's STEREO LINK switch: on, ONE auto-gain path is driven by both legs' summed energy, so the image cannot shift under the level match; off, each leg matches its own (`omx_drive.h`'s `struct omx_drive.stereo_link`, spec §4e). A field of the console's drive row (`DriveState.stereoLink`), on at come-up there and in omx-dsp's drive face.
+ * @see data/kernels/drive.json
+ */
+export declare const DRIVE_STEREO_LINKS: readonly ["off", "on"];
+
+/**
+ * The drive's post-curve HIGH-FREQUENCY ROLL-OFF corner, in Hz: the id is the corner, and 0 names no roll-off (the section does not run: `omx_drive.h`'s `struct omx_drive.hf_on` is 0). The console's drive row offers off, 12000 and 16000 (`DriveState.hfRolloff`, `DRIVE_HF_ROLLOFFS`) and comes up off, as omx-dsp's drive face does.
+ * @see data/kernels/drive.json
+ */
+export declare const DRIVE_HF_ROLLOFFS: readonly [0, 12000, 16000];
+
 /**
  * The bias at `character = +1`, in the SHAPER's own input units — `OMX_DRIVE_BIAS_MAX`. DERIVED, not chosen (§4b). In the saturating limit every knee tends to `sgn`, the output is a rectangular wave of duty `d = ½ + asin(b)/π`, and its `n`th harmonic goes as `sin(nπd)/n` — so `|H2|` is maximal at `d = ¾`, which is `b = sin(π/4) = 1/√2` exactly. Measured too: the H2-maximising bias for a full-scale sine at unity drive is 0.712 (soft), 0.658 (tape), 0.645 (tube), and this one value costs 0.000 / 0.035 / 0.088 dB of H2 against each curve's own optimum. ONE normalised bias for all three knees, not three.
  * @see data/kernels/drive.json
  */
 export declare const DRIVE_BIAS_MAX: 0.7071067811865476;
 
+/**
+ * The HPF's switch: off, the filter is not in the EQ's bank at all; on, its one or two Butterworth sections run after the bands. It comes up off, on the console's channel EQ and in omx-dsp's EQ face (see EQ_PASS_FILTER_DEFAULTS).
+ * @see data/kernels/eq.json
+ */
+export declare const EQ_HPF_ONS: readonly ["off", "on"];
+
+/**
+ * Where the HPF cutoff can sit (low end); mirrors the drawn low-frequency handle.
+ * @see data/kernels/eq.json
+ */
+export declare const HPF_FREQ_RANGE: {
+  readonly min: 20;
+  readonly max: 1000;
+  readonly step: 10;
+  readonly unit: "Hz";
+};
+
+/**
+ * The pass-filter slopes the EQ offers, in dB per octave: the HPF's slope, and by use the LPF's. The id is the slope: 12 is one maximally flat section, 24 the two-section Butterworth.
+ * @see data/kernels/eq.json
+ */
+export declare const FILTER_SLOPES: readonly [12, 24];
+
+/**
+ * The LPF's switch: off, the filter is not in the EQ's bank at all; on, its one or two Butterworth sections run after the bands and the HPF. It comes up off, on the console's channel EQ and in omx-dsp's EQ face (see EQ_PASS_FILTER_DEFAULTS).
+ * @see data/kernels/eq.json
+ */
+export declare const EQ_LPF_ONS: readonly ["off", "on"];
+
+/**
+ * Where the LPF cutoff can sit (high end).
+ * @see data/kernels/eq.json
+ */
+export declare const LPF_FREQ_RANGE: {
+  readonly min: 1000;
+  readonly max: 20000;
+  readonly step: 10;
+  readonly unit: "Hz";
+};
+
+/**
+ * The generic EQ band shapes, in the order a picker offers them and in the order of the integer a plugin host sees on a band type port. The id is the name; the position is the value. A bell is the shape a band added by the operator starts as.
+ * @see data/kernels/eq.json
+ */
+export declare const EQ_BAND_TYPES: readonly ["bell", "lowShelf", "highShelf", "notch", "allpass1", "allpass2"];
+
 /**
  * The frequency band a parametric band can be dragged across.
  * @see data/kernels/eq.json
@@ -551,38 +633,10 @@ export declare const EQ_NOTCH_Q_RANGE: {
 };
 
 /**
- * Where the HPF cutoff can sit (low end); mirrors the drawn low-frequency handle.
+ * A band's switch. Off, the band is not in the EQ's bank (the slots close up); on, it runs, parked when it is a gain-carrying shape at 0 dB. No come-up value is declared, because the strips differ: the console's channel EQ brings its default bands up on, an omx-eq plugin brings every band up off so a racked instance is a wire.
  * @see data/kernels/eq.json
  */
-export declare const HPF_FREQ_RANGE: {
-  readonly min: 20;
-  readonly max: 1000;
-  readonly step: 10;
-  readonly unit: "Hz";
-};
-
-/**
- * Where the LPF cutoff can sit (high end).
- * @see data/kernels/eq.json
- */
-export declare const LPF_FREQ_RANGE: {
-  readonly min: 1000;
-  readonly max: 20000;
-  readonly step: 10;
-  readonly unit: "Hz";
-};
-
-/**
- * The generic EQ band shapes, in the order a picker offers them and in the order of the integer a plugin host sees on a band type port. The id is the name; the position is the value. A bell is the shape a band added by the operator starts as.
- * @see data/kernels/eq.json
- */
-export declare const EQ_BAND_TYPES: readonly ["bell", "lowShelf", "highShelf", "notch", "allpass1", "allpass2"];
-
-/**
- * The pass-filter slopes the EQ offers, in dB per octave. The id is the slope: 12 is one maximally flat section, 24 the two-section Butterworth.
- * @see data/kernels/eq.json
- */
-export declare const FILTER_SLOPES: readonly [12, 24];
+export declare const EQ_BAND_ONS: readonly ["off", "on"];
 
 /**
  * The maximum number of parametric bands a channel EQ may hold — the operator can add up to this many. Generated into `omx_contract_limits.h` as `OMX_EQ_MAX_BANDS`, which `omx_biquad.h` reads (`output-delay-ceiling.test.ts` reads the header): the native lane allocates exactly this many biquad slots per channel and silently clamps above it, so the model, the wire, and the DSP agree by test, not by memory.