@openmixer/omx-contract 1.2.1 → 2.0.0

package/data/kernels/eq.json

@@ -1,119 +1,290 @@
 {
   "$schema": "../../schema/omx-contract.schema.json",
-  "EQ_MAX_BANDS": {
-    "kind": "scalar",
-    "doc": "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.",
-    "unit": "",
-    "value": 24
-  },
-  "ISO_THIRD_OCTAVE_CENTRES_HZ": {
-    "kind": "list",
-    "doc": "The standard ISO 266 one-third-octave centre frequencies, 20 Hz–20 kHz (31 bands) — the classic 31-band graphic-EQ layout's centres.",
-    "unit": "Hz",
-    "values": [
-      20,
-      25,
-      31.5,
-      40,
-      50,
-      63,
-      80,
-      100,
-      125,
-      160,
-      200,
-      250,
-      315,
-      400,
-      500,
-      630,
-      800,
-      1000,
-      1250,
-      1600,
-      2000,
-      2500,
-      3150,
-      4000,
-      5000,
-      6300,
-      8000,
-      10000,
-      12500,
-      16000,
-      20000
-    ],
-    "c": {
-      "render": false
+  "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": "hpfFreq",
+      "kind": "travel",
+      "global": "HPF_FREQ_RANGE",
+      "doc": "Where the HPF cutoff can sit (low end); mirrors the drawn low-frequency handle.",
+      "travel": {
+        "min": 20,
+        "max": 1000,
+        "step": 10,
+        "unit": "Hz"
+      }
+    },
+    {
+      "name": "lpfFreq",
+      "kind": "travel",
+      "global": "LPF_FREQ_RANGE",
+      "doc": "Where the LPF cutoff can sit (high end).",
+      "travel": {
+        "min": 1000,
+        "max": 20000,
+        "step": 10,
+        "unit": "Hz"
+      }
+    },
+    {
+      "name": "bandType",
+      "kind": "choice",
+      "doc": "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.",
+      "ids": [
+        "bell",
+        "lowShelf",
+        "highShelf",
+        "notch",
+        "allpass1",
+        "allpass2"
+      ],
+      "default": "bell",
+      "labels": [
+        "Bell",
+        "Low Shelf",
+        "High Shelf",
+        "Notch",
+        "All-pass 1st",
+        "All-pass 2nd"
+      ]
+    },
+    {
+      "name": "filterSlope",
+      "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.",
+      "ids": [
+        12,
+        24
+      ],
+      "default": 12
     }
-  },
-  "GEQ_BANDS": {
-    "kind": "scalar",
-    "doc": "The graphic EQ's section count: DERIVED from ISO_THIRD_OCTAVE_CENTRES_HZ, never a second literal. Generated into `omx_contract_limits.h` as `OMX_GEQ_BANDS`, which sizes `mix_geq.h`'s section array — its OWN budget, never a claimant on EQ_MAX_BANDS (graphic-eq-31 spec §3, roster ruling 3).",
-    "unit": "",
-    "value": {
-      "derive": "count",
-      "of": "ISO_THIRD_OCTAVE_CENTRES_HZ"
-    }
-  },
-  "EQ_FREQ_RANGE": {
-    "kind": "travels",
-    "doc": "The frequency band a parametric band can be dragged across.",
-    "travel": {
-      "min": 20,
-      "max": 20000,
-      "step": 10,
-      "unit": "Hz"
-    }
-  },
-  "EQ_GAIN_RANGE": {
-    "kind": "travels",
-    "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"
-    }
-  },
-  "EQ_Q_RANGE": {
-    "kind": "travels",
-    "doc": "The Q (resonance) extent of a parametric band.",
-    "travel": {
-      "min": 0.3,
-      "max": 8,
-      "step": 0.1,
-      "unit": ""
-    }
-  },
-  "EQ_NOTCH_Q_RANGE": {
-    "kind": "travels",
-    "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": ""
-    }
-  },
-  "HPF_FREQ_RANGE": {
-    "kind": "travels",
-    "doc": "Where the HPF cutoff can sit (low end); mirrors the drawn low-frequency handle.",
-    "travel": {
-      "min": 20,
-      "max": 1000,
-      "step": 10,
-      "unit": "Hz"
-    }
-  },
-  "LPF_FREQ_RANGE": {
-    "kind": "travels",
-    "doc": "Where the LPF cutoff can sit (high end).",
-    "travel": {
-      "min": 1000,
-      "max": 20000,
-      "step": 10,
-      "unit": "Hz"
+  ],
+  "constants": {
+    "EQ_MAX_BANDS": {
+      "kind": "scalar",
+      "doc": "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.",
+      "unit": "",
+      "value": 24
+    },
+    "ISO_THIRD_OCTAVE_CENTRES_HZ": {
+      "kind": "list",
+      "doc": "The standard ISO 266 one-third-octave centre frequencies, 20 Hz–20 kHz (31 bands) — the classic 31-band graphic-EQ layout's centres.",
+      "unit": "Hz",
+      "values": [
+        20,
+        25,
+        31.5,
+        40,
+        50,
+        63,
+        80,
+        100,
+        125,
+        160,
+        200,
+        250,
+        315,
+        400,
+        500,
+        630,
+        800,
+        1000,
+        1250,
+        1600,
+        2000,
+        2500,
+        3150,
+        4000,
+        5000,
+        6300,
+        8000,
+        10000,
+        12500,
+        16000,
+        20000
+      ]
+    },
+    "GEQ_BANDS": {
+      "kind": "scalar",
+      "doc": "The graphic EQ's section count: DERIVED from ISO_THIRD_OCTAVE_CENTRES_HZ, never a second literal. Generated into `omx_contract_limits.h` as `OMX_GEQ_BANDS`, which sizes `mix_geq.h`'s section array — its OWN budget, never a claimant on EQ_MAX_BANDS (graphic-eq-31 spec §3, roster ruling 3).",
+      "unit": "",
+      "value": {
+        "derive": "count",
+        "of": "ISO_THIRD_OCTAVE_CENTRES_HZ"
+      }
+    },
+    "OPERATOR_EQ_BANDS_RESERVE": {
+      "kind": "scalar",
+      "doc": "The band slots kept for the operator's own hand: the reserve the feedback suppressor and the ring correction may never eat into. Nine is the working set a live EQ actually holds. The budget OPERATOR_EQ_BANDS_RESERVE + FBS_DEFAULT_MAX_AUTO_BANDS + HRP_DEFAULT_MAX_AUTO_BANDS (9 + 6 + 8 = 23) must fit EQ_MAX_BANDS, and `omx-contract validate` refuses data where it does not.",
+      "unit": "",
+      "value": 9
+    },
+    "EQ_BAND_COUNTS": {
+      "kind": "sheet",
+      "doc": "How many bands each strip type's EQ starts with (`default`) and may hold (`max`). `channel` is the console's channel strip: it starts with four and the operator adds bands up to EQ_MAX_BANDS (a band added takes the frequency it is added at, so no default is declared for it). `strip` is the omx-strip plugin's EQ and `eq8`, `eq16` and `eq32` the omx-eq plugins, whose bands are fixed. A default may never exceed its maximum, and the default centres of any count come from the one default rule, whatever the strip.",
+      "value": {
+        "channel": {
+          "default": 4,
+          "max": {
+            "ref": "EQ_MAX_BANDS"
+          }
+        },
+        "strip": {
+          "default": 4,
+          "max": 4
+        },
+        "eq8": {
+          "default": 8,
+          "max": 8
+        },
+        "eq16": {
+          "default": 16,
+          "max": 16
+        },
+        "eq32": {
+          "default": 32,
+          "max": 32
+        }
+      }
+    },
+    "EQ_BAND_DEFAULTS": {
+      "kind": "sheet",
+      "doc": "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.",
+      "value": {
+        "gainDb": 0,
+        "q": 1
+      }
+    },
+    "EQ_PASS_FILTER_DEFAULTS": {
+      "kind": "sheet",
+      "doc": "The corners the high-pass and low-pass filters of a fresh EQ are parked at, whatever the strip. Both come up off.",
+      "value": {
+        "hpfFreqHz": 80,
+        "lpfFreqHz": 18000
+      }
+    },
+    "EQ_DEFAULT_CENTRES_FOUR_BAND_HZ": {
+      "kind": "list",
+      "doc": "The default band centres of a four-band EQ, Hz: ISO 266 preferred values, two to two and a half octaves apart. The default rule gives every other band count its centres from the preferred series; four bands start here.",
+      "unit": "Hz",
+      "values": [
+        100,
+        400,
+        2000,
+        8000
+      ]
+    },
+    "EQ_CENTRE_SERIES_R20_HZ": {
+      "kind": "list",
+      "doc": "The ISO 266 R20 preferred frequencies from 20 Hz to 20 kHz (61 values, sixth-octave spacing): the finer series the default band rule falls back to where R10 (ISO_THIRD_OCTAVE_CENTRES_HZ, 31 values) has too few to give every band its own centre. R10 is a subset of it.",
+      "unit": "Hz",
+      "values": [
+        20,
+        22.4,
+        25,
+        28,
+        31.5,
+        35.5,
+        40,
+        45,
+        50,
+        56,
+        63,
+        71,
+        80,
+        90,
+        100,
+        112,
+        125,
+        140,
+        160,
+        180,
+        200,
+        224,
+        250,
+        280,
+        315,
+        355,
+        400,
+        450,
+        500,
+        560,
+        630,
+        710,
+        800,
+        900,
+        1000,
+        1120,
+        1250,
+        1400,
+        1600,
+        1800,
+        2000,
+        2240,
+        2500,
+        2800,
+        3150,
+        3550,
+        4000,
+        4500,
+        5000,
+        5600,
+        6300,
+        7100,
+        8000,
+        9000,
+        10000,
+        11200,
+        12500,
+        14000,
+        16000,
+        18000,
+        20000
+      ]
     }
   }
 }

package/data/kernels/fbs.json

@@ -0,0 +1,150 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "constants": {
+    "SUBHARMONIC_RADIUS_BINS": {
+      "kind": "scalar",
+      "doc": "How far (bins) around bin/2 and bin/3 PSHR (`omx_fbs_pshr`) scans for a sub-harmonic line. A true half/third partial lands mid-bin in the worst case (bin/2 and bin/3 are rarely integers) and spectral leakage smears it one bin further; ±2 covers both. Measured on the #116 live-music corpus: every false positive's sub-line sat inside this window. Deliberately NOT wider — at low bins the window is already a large fraction of an octave, and widening it would start reading unrelated program lines as \"sub-harmonics\" of real feedback.",
+      "unit": "",
+      "value": 2
+    },
+    "FBS_PAPR_GUARD_BINS": {
+      "kind": "scalar",
+      "doc": "PAPR's guard band: bins either side of the peak left out of the floor average (its own skirt).",
+      "unit": "",
+      "value": 2
+    },
+    "FBS_PNPR_RADIUS_BINS": {
+      "kind": "scalar",
+      "doc": "PNPR's neighbourhood radius in bins, and the guard inside it that belongs to the peak's own skirt: a pure tone is compared with bins 2 and 3 away on each side.",
+      "unit": "",
+      "value": 3
+    },
+    "FBS_PNPR_GUARD_BINS": {
+      "kind": "scalar",
+      "doc": "The guard inside PNPR's neighbourhood radius that belongs to the peak's own skirt, in bins.",
+      "unit": "",
+      "value": 1
+    },
+    "FBS_PHPR_HARMONICS": {
+      "kind": "scalar",
+      "doc": "How many harmonics PHPR reads above the candidate: 2f, 3f and 4f.",
+      "unit": "",
+      "value": 3
+    },
+    "FBS_PSHR_SELF_SKIP_BINS": {
+      "kind": "scalar",
+      "doc": "PSHR skips sub-window bins within this many of the candidate, so a low bin never measures its own skirt as a sub-harmonic.",
+      "unit": "",
+      "value": 3
+    },
+    "FBS_FLOOR_LIN": {
+      "kind": "scalar",
+      "doc": "The magnitude floor of every detector dB reading (−240 dB): a zero bin stays finite.",
+      "unit": "",
+      "value": 1e-12
+    },
+    "FBS_TRACK_SLOTS": {
+      "kind": "scalar",
+      "doc": "Tracked candidate bins per armed channel. A candidate that finds no free slot is COUNTED and reported, never dropped silently; the identity corpus peaks at 34.",
+      "unit": "",
+      "value": 512
+    },
+    "PSHR_MIN_DB": {
+      "kind": "scalar",
+      "doc": "Minimum PSHR (`omx_fbs_pshr`) (dB) for a candidate frame to count as sub-harmonic-CLEAN. Evidence-set on the #116 corpus, margin on both sides: the four live false positives (musical overtones at 1 869.1 / 832.0 / 263.7 / 228.5 Hz) read PSHR between −10.2 and +8.8 dB across their windows — never a 5-frame sub-clean stretch, and the single closest approach (+8.8) is isolated between frames at ≈ −1 and −10 — while the committed #106 injected ramp reads ≥ +12.2 dB from its second frame on (its frame 0 sits at +9.4, costing exactly one frame of confirm latency, pinned in the corpus test). A static program line at f/2 of REAL feedback also clears this fast: the runaway gains several dB per hop on anything static, so the deferral is transient.",
+      "unit": "dB",
+      "value": 10
+    },
+    "GROWTH_WINDOW_FRAMES": {
+      "kind": "scalar",
+      "doc": "How many of a candidate bin's most recent dB readings feed the growth-slope estimate (the engine's least-squares slope) — set equal to DEFAULT_THRESHOLDS's `persistFrames` so growth is judged over the SAME window persistence already demands (the full run since the bin became a candidate, not a shorter or longer slice of it). Long enough that a couple of noisy/vibrato frames can't fake a trend by themselves.",
+      "unit": "",
+      "value": 5
+    },
+    "DEEP_PLATEAU_FRAMES": {
+      "kind": "scalar",
+      "doc": "The DEEP plateau tier's dwell: ~2 s at the watcher's 10 Hz — the TIME that buys the deeper floor its music safety (see DetectThresholds.deepPlateauFloorDb).",
+      "unit": "",
+      "value": 20
+    },
+    "GROWTH_MIN_DB_PER_FRAME": {
+      "kind": "scalar",
+      "doc": "Minimum least-squares slope, in dB PER FRAME, over GROWTH_WINDOW_FRAMES for a bin to count as \"running away\" rather than merely holding level. Set with real margin on BOTH sides — comfortably above measurement jitter on a held tone or a quiet/broadband mix (well under 0.2 dB/frame in practice) and comfortably below a genuine feedback ramp, which climbs several dB across a handful of ~20 ms hops as it heads toward clipping. Issue #91's acceptance bar is \"arming must never burst-alarm on non-growing content\", so this errs conservative (under-fire a marginal ramp) rather than tight (risk a false alarm) — the ramp gate (`omx_fbs_is_growing`) also requires the window's end to sit above its start, a cheap belt-and-braces check against a fit dragged positive by one mid-window wobble.",
+      "unit": "dB",
+      "value": 0.8
+    },
+    "GROWTH_MAX_DIP_DB": {
+      "kind": "scalar",
+      "doc": "Largest single-frame DIP (dB) a run-away window may contain. Real feedback climbs every hop; a small allowance covers measurement jitter and the −0.3 dB-ish wobble frames seen on live captures, while any real drop (a note ending, tremolo) breaks the run.",
+      "unit": "dB",
+      "value": 0.5
+    },
+    "GROWTH_MIN_TOTAL_RISE_DB": {
+      "kind": "scalar",
+      "doc": "Minimum END-TO-END rise (dB) across the window. The live-music corpus (issue #106) showed sustained melody notes drifting up ~4–5 dB over a window without ever being feedback; a loop past unity gains several dB per hop and clears 6 dB in a window trivially. Below this the tone is holding level, not running away.",
+      "unit": "dB",
+      "value": 6
+    },
+    "GROWTH_MAX_SINGLE_FRAME_SHARE": {
+      "kind": "scalar",
+      "doc": "Cap on the share of the window's total rise a SINGLE frame may carry. Feedback is exponential in amplitude ⇒ linear in dB ⇒ its rise is distributed roughly evenly across the window; a musical attack / re-articulation puts almost the whole rise in one hop (the exact shape behind every one of issue #106's 72 live false positives). One half is generous to real ramps (an even N-frame ramp puts 1/(N−1) per hop) and fatal to steps. A side effect worth knowing: a 2-sample window can never pass (one hop IS the whole rise), so confirmation always rests on at least three frames of actual ramp evidence.",
+      "unit": "",
+      "value": 0.5
+    },
+    "GROWTH_CONFIRM_FRAMES": {
+      "kind": "scalar",
+      "doc": "How many CONSECUTIVE frames the ramp gate (`omx_fbs_is_growing`) must hold before a bin confirms — the time-domain tiebreak for the one shape a single window cannot judge (issue #106): a smooth musical crescendo. Within one window a +6 dB swell (live corpus: a C6 at 1 049 Hz, `[-53.7, -51.4, -50.4, -48, -47.3]`) is indistinguishable from slow feedback — the difference is only visible on the NEXT hop, where a crescendo peaks and plateaus (the window's rise collapses) while feedback keeps climbing. Requiring the gate to hold twice in a row costs a clean ramp nothing — its gate is already true while persistence is still arming — and blocks the swell that peaks the very frame it would have confirmed.",
+      "unit": "",
+      "value": 2
+    },
+    "DEFAULT_THRESHOLDS": {
+      "kind": "sheet",
+      "doc": "The corpus-tuned SAFE DEFAULT — today's exact gates, assembled byte-for-byte from the exported consts above (which stay the authoritative literal source, so the corpus test's import type { MagnitudeSeries } from './spectrum-bands.js'; imports remain the single truth). This is the ANCHOR the whole sensitivity mapping pins to: thresholdsFor`(0, 'live')` and `(0, 'fixed')` both deep-equal this object, so an untouched channel runs the identical detector it does now. `plateauFloorDb` is omitted ⇒ the #140 plateau route is OFF at the default.",
+      "value": {
+        "paprDb": 18,
+        "pnprDb": 12,
+        "phprDb": 9,
+        "persistFrames": 5,
+        "growthConfirmFrames": {
+          "ref": "GROWTH_CONFIRM_FRAMES"
+        },
+        "subCleanFrames": {
+          "ref": "GROWTH_WINDOW_FRAMES"
+        },
+        "growthMinTotalRiseDb": {
+          "ref": "GROWTH_MIN_TOTAL_RISE_DB"
+        },
+        "growthMaxSingleFrameShare": {
+          "ref": "GROWTH_MAX_SINGLE_FRAME_SHARE"
+        },
+        "growthMinDbPerFrame": {
+          "ref": "GROWTH_MIN_DB_PER_FRAME"
+        },
+        "growthMaxDipDb": {
+          "ref": "GROWTH_MAX_DIP_DB"
+        },
+        "pshrMinDb": {
+          "ref": "PSHR_MIN_DB"
+        }
+      }
+    },
+    "FBS_MAX_NOTCH_DEPTH_DB": {
+      "kind": "scalar",
+      "doc": "THE NOTCH DEPTH LAW: the deepest cut any machine planter may propose from one reading, in dB. A number, not a literal at the call site, because two planters now lean on it. FBS derives a candidate's depth from the peak-to-average ratio around its bin and stops here; Room Analysis derives a mode's depth from its height above the median curve and is held to the SAME ceiling (2026-09-08-room-analysis.md §4 — \"never more than the FBS notch depth law\"). Written twice as `18` those two bounds would be equal by coincidence and could drift apart in silence. It is a CEILING ON THE PROPOSAL, not the final gain: a band that lands as a rampable BELL is bounded again by `EQ_GAIN_RANGE`, which is tighter. A planter must honour both and REPORT when either bit, never quietly deliver a shallower cut than it was asked for.",
+      "unit": "dB",
+      "value": 18
+    },
+    "FBS_DEFAULT_NOTCH_Q": {
+      "kind": "scalar",
+      "doc": "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.",
+      "unit": "",
+      "value": 116
+    },
+    "FBS_DEFAULT_MAX_AUTO_BANDS": {
+      "kind": "scalar",
+      "doc": "Default per-channel cap on auto-planted bands — a full pool plants nothing and raises a pool-full alert instead (predictability over silent eviction).",
+      "unit": "",
+      "value": 6
+    }
+  }
+}