@openmixer/omx-contract 1.0.0 → 1.2.0

package/README.md

@@ -3,14 +3,15 @@
 # omx-contract
 
 The FreeMixer declarations as data: what a value may be (a travel, a default, a kernel constant, a
-list, a plugin's parameter selection), as JSON validated by a JSON Schema, rendered by one CLI into
+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.
+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.
 
 ```
 data/                        the declaration, one file per group, edited by hand
-  rates.json  primitives.json  kernels/<kernel>.json  plugins/<plugin>.json
+  rates.json  primitives.json  kernels/<kernel>.json
 schema/omx-contract.schema.json   JSON Schema 2020-12: five kinds, closed units, refs, closed derivations
 bin/omx-contract.mjs         the CLI
 render/                      c.mjs (openmixer's renderer, moved unchanged, under c/), ts.mjs, json.mjs
@@ -18,6 +19,8 @@ include/omxcontract/         the committed c render (what omx-contract-devel ins
 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)
 ```
@@ -38,11 +41,12 @@ share/omx-contract` and `render --target ts --out test/golden/ts`; CI holds all
 
 ## Consuming it
 
-Pin one version (`omx-contract 1.0.0` in `.github/pins.txt`) and build against its renders, committing
+Pin one version (`omx-contract 1.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=1.0.0 omx-contract`), else the release's npm tarball, unpacked, and
+(`pkg-config --exact-version=1.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>` and `<omxcontract/params/omx_delay_params.h>`.
+`<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).
 
 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.

package/data/kernels/balance.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "PAN_RANGE": {
+    "kind": "travels",
+    "doc": "The PAN travel — −1 (hard left) … 0 (center) … +1 (hard right). A property of the pan law itself, not of any desk, so it is declared once. Continuous: a pan position has no quantum, and panGains clamps to these bounds.",
+    "travel": {
+      "min": -1,
+      "max": 1,
+      "step": 0,
+      "unit": ""
+    },
+    "c": {
+      "alias": {
+        "fact": "pan",
+        "field": "pan"
+      }
+    }
+  }
+}

package/data/kernels/chorus.json

@@ -11,5 +11,53 @@
       "default": 0,
       "defaultFrom": "desk"
     }
+  },
+  "CHORUS_RATE_RANGE": {
+    "kind": "travels",
+    "doc": "The chorus sweep's speed (§3a). Above ~3 Hz it stops being a chorus and becomes a vibrato.",
+    "travel": {
+      "min": 0.05,
+      "max": 8,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 0.6,
+      "defaultFrom": "desk"
+    }
+  },
+  "CHORUS_DEPTH_RANGE": {
+    "kind": "travels",
+    "doc": "The chorus's peak-to-peak excursion above its declared 10 ms base (§3a).",
+    "travel": {
+      "min": 0,
+      "max": 12,
+      "step": 0.1,
+      "unit": "ms",
+      "default": 4,
+      "defaultFrom": "desk"
+    }
+  },
+  "CHORUS_VOICES_RANGE": {
+    "kind": "travels",
+    "doc": "The chorus's tap count — one oscillator read at k/N (§3a).",
+    "travel": {
+      "min": 1,
+      "max": 4,
+      "step": 1,
+      "unit": "",
+      "default": 3,
+      "defaultFrom": "desk"
+    }
+  },
+  "CHORUS_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The chorus's wet/dry, as an instance of DRIVE_MIX_RANGE — the same percent travel, its own come-up value: 35 %, a colour under the dry on a strip (§3a). The REVERB_LOWCUT_RANGE-over- REVERB_CUT_RANGE shape: one travel, one declared default per field that reads it.",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 0.1,
+      "unit": "%",
+      "default": 35,
+      "defaultFrom": "desk"
+    }
   }
 }

package/data/kernels/deesser.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "DEESS_FREQ_RANGE": {
+    "kind": "travels",
+    "doc": "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).",
+    "travel": {
+      "min": 2000,
+      "max": 16000,
+      "step": 10,
+      "unit": "Hz",
+      "default": 7000,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_WIDTH_RANGE": {
+    "kind": "travels",
+    "doc": "The band's WIDTH, in OCTAVES around the centre: the edges are `f / 2^(w/2)` and `f · 2^(w/2)`, which is what makes the centre the geometric middle at every width. Octaves and not a Q, because a Q is a property of one section and this band is TWO (a highpass and a lowpass, `mix_deesser.h`) — an operator asked to dial a Q would be dialling a number neither filter carries. One octave is the classic de-esser band: wide enough for a sibilant that moves with the vowel, narrow enough that a 1 kHz vowel sits 27.8 dB down the skirt.",
+    "travel": {
+      "min": 0.25,
+      "max": 4,
+      "step": 0.05,
+      "unit": "oct",
+      "default": 1,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_THRESHOLD_RANGE": {
+    "kind": "travels",
+    "doc": "Where reduction starts — the level of the BAND, not of the strip, which is why the come-up is so much lower than the compressor's. A vocal peaking −12 dBFS carries roughly −30 dBFS in a one-octave band at 7 kHz on its sibilants and under −40 on its vowels, so −30 sits between the two and the stage opens on an \"s\" and stays shut on an \"ah\".",
+    "travel": {
+      "min": -60,
+      "max": 0,
+      "step": 0.5,
+      "unit": "dB",
+      "default": -30,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_RATIO_RANGE": {
+    "kind": "travels",
+    "doc": "How hard the band is held once it is over the threshold. 4:1 is the textbook de-esser ratio: firm on the \"s\", short of a limiter.",
+    "travel": {
+      "min": 1,
+      "max": 20,
+      "step": 0.1,
+      "unit": "",
+      "default": 4,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_RANGE_RANGE": {
+    "kind": "travels",
+    "doc": "The FLOOR on the reduction, in dB and never positive — the deepest cut the stage may reach however loud the sibilant is (`mix_deesser.h`'s clamp, §4c). 12 dB tames a hard sibilant; past that a voice starts to lisp, and a de-esser with NO floor turns a shouted \"s\" into a hole. The ceiling is 0, which switches the reduction off without switching the stage off — a legitimate thing to want while dialling the band in by ear.",
+    "travel": {
+      "min": -24,
+      "max": 0,
+      "step": 0.5,
+      "unit": "dB",
+      "default": -12,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_ATTACK_RANGE": {
+    "kind": "travels",
+    "doc": "The detector's ATTACK, in ms. A sibilant's onset is a few milliseconds; 1 ms catches it without the detector chattering on the band's own waveform.",
+    "travel": {
+      "min": 0.1,
+      "max": 50,
+      "step": 0.1,
+      "unit": "ms",
+      "default": 1,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_RELEASE_RANGE": {
+    "kind": "travels",
+    "doc": "The detector's RELEASE, in ms. 60 ms is long enough not to modulate inside one \"s\" and short enough to be open again for the next syllable.",
+    "travel": {
+      "min": 5,
+      "max": 500,
+      "step": 1,
+      "unit": "ms",
+      "default": 60,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_KNEE_DB": {
+    "kind": "scalar",
+    "doc": "The knee, in dB — a CONSTANT of the stage and not a row field (`2026-09-22-native-deesser-stage.md` §4b): a de-esser without a soft knee latches audibly on the first sibilant of a phrase, and no other value of this number is a de-esser anyone would dial. The controller pushes it to the node and this is the same number; a second spelling would be a picture that disagrees with the audio about where the reduction starts.",
+    "unit": "dB",
+    "value": 6
+  }
+}

package/data/kernels/drive.json

@@ -8,5 +8,95 @@
       "derive": "sqrt",
       "of": 0.5
     }
+  },
+  "DRIVE_AMOUNT_RANGE": {
+    "kind": "travels",
+    "doc": "The PRE-CURVE gain, in dB. 0 dB is unity into the curve, so a stage switched on at its defaults changes almost nothing — which is what an `on` switch should mean. The ceiling is where every curve is saturating hard on any signal a console carries.",
+    "travel": {
+      "min": 0,
+      "max": 36,
+      "step": 0.1,
+      "unit": "dB",
+      "default": 0,
+      "defaultFrom": "desk"
+    },
+    "c": {
+      "alias": {
+        "fact": "drive",
+        "field": "driveDb"
+      }
+    }
+  },
+  "DRIVE_CHARACTER_RANGE": {
+    "kind": "travels",
+    "doc": "The EVEN/ODD harmonic balance. −1 is pure odd (the curve itself), +1 is pure even, 0 an equal blend — the kernel splits its own distortion residue into an odd and an even half and fades between them, so the two ends are exact rather than approximate (`mix_drive.h`, measured: H2 at −317 dBc at −1, H3 at −118 dBc at +1). Unitless, and signed by construction. NOT NORMALIZED_RANGE: this is a BALANCE with a meaningful centre, and a 0..1 travel would put its centre at 0.5 and its neutral nowhere.",
+    "travel": {
+      "min": -1,
+      "max": 1,
+      "step": 0.01,
+      "unit": "",
+      "default": 0,
+      "defaultFrom": "desk"
+    },
+    "c": {
+      "alias": {
+        "fact": "drive",
+        "field": "character"
+      }
+    }
+  },
+  "DRIVE_BAND_FREQ_RANGE": {
+    "kind": "travels",
+    "doc": "The band split / tilt corner, in Hz. ONE travel for all three band modes, because the C imposes one constraint on all of them: it is the corner of a single biquad, and the split's other half is `x − LP(x)`. The full audio band, not the channel filters' narrower HPF/LPF pair — the same reasoning REVERB_CUT_RANGE records: a surface narrower than the row removes reach the console genuinely has.",
+    "travel": {
+      "min": 20,
+      "max": 20000,
+      "step": 1,
+      "unit": "Hz",
+      "default": 2000,
+      "defaultFrom": "desk"
+    },
+    "c": {
+      "alias": {
+        "fact": "drive",
+        "field": "bandHz"
+      }
+    }
+  },
+  "DRIVE_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The wet/dry, as a PERCENT — the unit a drive control is read in on every desk that has one. Deliberately not NORMALIZED_RANGE (which is unitless 0..1): a mix a surface must label \"0.35\" when the operator thinks in \"35 %\" is a control whose declaration is fighting its reader. The kernel divides by 100 where it resolves the atom, in one place. The come-up is 100 %, not the reverb's modest 30: a saturator's insert use is IN the path. The `exciter` curve seeds itself lower (DRIVE_EXCITER_SEED), because that is a property of the TOPOLOGY and not of the travel.",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 0.1,
+      "unit": "%",
+      "default": 100,
+      "defaultFrom": "desk"
+    },
+    "c": {
+      "alias": {
+        "fact": "drive",
+        "field": "mix"
+      }
+    }
+  },
+  "DRIVE_TRIM_RANGE": {
+    "kind": "travels",
+    "doc": "The POST-stage make-up, in dB. Symmetric enough either way that an operator can null the stage in and out against the bypass, which is how a colour stage is actually judged.",
+    "travel": {
+      "min": -24,
+      "max": 12,
+      "step": 0.1,
+      "unit": "dB",
+      "default": 0,
+      "defaultFrom": "desk"
+    },
+    "c": {
+      "alias": {
+        "fact": "drive",
+        "field": "trimDb"
+      }
+    }
   }
 }

package/data/kernels/eq.json

@@ -55,5 +55,65 @@
       "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"
+    }
   }
 }

package/data/kernels/flanger.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "FLANGER_RATE_RANGE": {
+    "kind": "travels",
+    "doc": "The flanger's jet sweep (§3b).",
+    "travel": {
+      "min": 0.05,
+      "max": 5,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 0.25,
+      "defaultFrom": "desk"
+    }
+  },
+  "FLANGER_DEPTH_RANGE": {
+    "kind": "travels",
+    "doc": "The flanger's peak-to-peak excursion above its declared 0.5 ms base (§3b).",
+    "travel": {
+      "min": 0,
+      "max": 5,
+      "step": 0.1,
+      "unit": "ms",
+      "default": 2,
+      "defaultFrom": "desk"
+    }
+  },
+  "FLANGER_FEEDBACK_RANGE": {
+    "kind": "travels",
+    "doc": "The flanger's SIGNED resonance (§3b). The ±0.95 clamp is DECLARED here — a PATCH asking for 1.0 is answered by this travel — and the kernel's own clamp is the enforcement half.",
+    "travel": {
+      "min": -0.95,
+      "max": 0.95,
+      "step": 0.01,
+      "unit": "",
+      "default": 0.6,
+      "defaultFrom": "desk"
+    }
+  },
+  "FLANGER_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The flanger's wet/dry, as an instance of DRIVE_MIX_RANGE: 50 %, equal dry and wet, where the comb is deepest (§3b).",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 0.1,
+      "unit": "%",
+      "default": 50,
+      "defaultFrom": "desk"
+    }
+  }
+}

package/data/kernels/geq.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "GEQ_BAND_RANGE": {
+    "kind": "travels",
+    "doc": "One graphic-EQ fader's travel: EQ_GAIN_RANGE by reference (a graphic fader is an EQ gain), with the come-up value it needs as a row field — flat, 0 dB (graphic-eq-31 spec §3).",
+    "travel": {
+      "min": -15,
+      "max": 15,
+      "step": 0.5,
+      "unit": "dB",
+      "default": 0,
+      "defaultFrom": "desk"
+    }
+  },
+  "GEQ_BAND_Q": {
+    "kind": "scalar",
+    "doc": "The graphic EQ's band Q: the ISO third-octave bandwidth, `2^(1/6)/(2^(1/3) − 1) ≈ 4.318`, to one decimal as the M32 GEQ carries it. Read by the `geq31` preset and the graphic EQ's section design (graphic-eq-31 spec §3).",
+    "unit": "",
+    "value": 4.3
+  },
+  "GEQ_PROTO_DB": {
+    "kind": "scalar",
+    "doc": "The prototype gain the `true` solve's first interaction matrix is evaluated at (spec §2, §3): the middle of the travel's magnitude, where a matched-Z section's dB response per dB of gain is closest to its average.",
+    "unit": "dB",
+    "value": 12
+  },
+  "GEQ_DESIGN_GAIN_MAX_DB": {
+    "kind": "scalar",
+    "doc": "The ceiling on a section gain the `true` solve may ask for (spec §3): above the travel's worst case (26.0 dB, the alternating ±15 set) with margin. A solve past it clamps and the row says so (`designClamped`), never silently.",
+    "unit": "dB",
+    "value": 30
+  }
+}

package/data/kernels/phaser.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "PHASER_RATE_RANGE": {
+    "kind": "travels",
+    "doc": "The phaser's sweep speed (§3). `omx_lfo_inc` freezes at Nyquist; this travel stays far below.",
+    "travel": {
+      "min": 0.05,
+      "max": 5,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 0.5,
+      "defaultFrom": "desk"
+    }
+  },
+  "PHASER_BASE_RANGE": {
+    "kind": "travels",
+    "doc": "The phaser's lowest centre frequency; the sweep runs upward from it (§3).",
+    "travel": {
+      "min": 50,
+      "max": 2000,
+      "step": 1,
+      "unit": "Hz",
+      "default": 200,
+      "defaultFrom": "desk"
+    }
+  },
+  "PHASER_DEPTH_RANGE": {
+    "kind": "travels",
+    "doc": "The sweep's span above `base`, in octaves; 0 is a static phaser at `base` (§3).",
+    "travel": {
+      "min": 0,
+      "max": 6,
+      "step": 0.1,
+      "unit": "oct",
+      "default": 4,
+      "defaultFrom": "desk"
+    }
+  },
+  "PHASER_STAGES_RANGE": {
+    "kind": "travels",
+    "doc": "The phaser's section count per leg — EVEN, 2 … 12 (§2: two sections per notch). Its ends are the kernel's state capacity (`OMX_PHASER_MAX_STAGES` reads `OMX_PHASER_STAGES_RANGE_MAX`); the row moves it through the closed member set PHASER_STAGE_COUNTS, which is derived from it.",
+    "travel": {
+      "min": 2,
+      "max": 12,
+      "step": 2,
+      "unit": "",
+      "default": 6,
+      "defaultFrom": "desk"
+    }
+  },
+  "PHASER_STAGE_COUNTS": {
+    "kind": "list",
+    "doc": "The member set the `stages` field accepts: PHASER_STAGES_RANGE walked by its step.",
+    "unit": "",
+    "values": [
+      2,
+      4,
+      6,
+      8,
+      10,
+      12
+    ]
+  },
+  "PHASER_FEEDBACK_RANGE": {
+    "kind": "travels",
+    "doc": "The phaser's SIGNED resonance (§3). ±0.9, tighter than the flanger's ±0.95: the loop runs through a time-varying chain. Declared here (the refusal half); the kernel's clamp is the enforcement half.",
+    "travel": {
+      "min": -0.9,
+      "max": 0.9,
+      "step": 0.01,
+      "unit": "",
+      "default": 0.4,
+      "defaultFrom": "desk"
+    }
+  },
+  "PHASER_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The phaser's wet/dry, as an instance of DRIVE_MIX_RANGE: 50 %, where the notch is complete (§3).",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 0.1,
+      "unit": "%",
+      "default": 50,
+      "defaultFrom": "desk"
+    }
+  },
+  "PHASER_TRAVELS": {
+    "kind": "travels",
+    "doc": "The phaser's continuous travels by row field — the ONE map its control bounds and its row travels both read (§3). `stages` is not here: it moves through PHASER_STAGE_COUNTS.",
+    "fields": {
+      "rateHz": {
+        "ref": "PHASER_RATE_RANGE"
+      },
+      "baseHz": {
+        "ref": "PHASER_BASE_RANGE"
+      },
+      "depthOct": {
+        "ref": "PHASER_DEPTH_RANGE"
+      },
+      "feedback": {
+        "ref": "PHASER_FEEDBACK_RANGE"
+      },
+      "mix": {
+        "ref": "PHASER_MIX_RANGE"
+      }
+    }
+  }
+}