@openmixer/omx-contract 1.0.0 → 1.1.0

package/README.md

@@ -3,14 +3,14 @@
 # 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, and 1.1.0 adds the flanger, de-esser, phaser, rotary, tremolo and graphic EQ kernels.
 
 ```
 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 +18,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 +40,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.1.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.1.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/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/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"
+      }
+    }
+  }
+}

package/data/kernels/rotary.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "ROTARY_HORN_SLOW_RANGE": {
+    "kind": "travels",
+    "doc": "The horn's chorale (slow) rate, Hz.",
+    "travel": {
+      "min": 0.1,
+      "max": 2,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 0.8,
+      "defaultFrom": "desk"
+    }
+  },
+  "ROTARY_HORN_FAST_RANGE": {
+    "kind": "travels",
+    "doc": "The horn's tremolo (fast) rate, Hz.",
+    "travel": {
+      "min": 3,
+      "max": 10,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 6.8,
+      "defaultFrom": "desk"
+    }
+  },
+  "ROTARY_DRUM_SLOW_RANGE": {
+    "kind": "travels",
+    "doc": "The drum's chorale (slow) rate, Hz.",
+    "travel": {
+      "min": 0.1,
+      "max": 2,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 0.7,
+      "defaultFrom": "desk"
+    }
+  },
+  "ROTARY_DRUM_FAST_RANGE": {
+    "kind": "travels",
+    "doc": "The drum's tremolo (fast) rate, Hz.",
+    "travel": {
+      "min": 3,
+      "max": 10,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 5.9,
+      "defaultFrom": "desk"
+    }
+  },
+  "ROTARY_ACCEL_RANGE": {
+    "kind": "travels",
+    "doc": "The scale on every speed-change time constant (`ROTARY_*_ACCEL_MS`/`_DECEL_MS`): 2 is twice as slow.",
+    "travel": {
+      "min": 0.25,
+      "max": 4,
+      "step": 0.01,
+      "unit": "x",
+      "default": 1,
+      "defaultFrom": "desk"
+    }
+  },
+  "ROTARY_BALANCE_RANGE": {
+    "kind": "travels",
+    "doc": "The drum/horn balance, percent: −100 drum only, +100 horn only; the law attenuates, never boosts.",
+    "travel": {
+      "min": -100,
+      "max": 100,
+      "step": 1,
+      "unit": "%",
+      "default": 0,
+      "defaultFrom": "desk"
+    }
+  },
+  "ROTARY_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The rotary's wet/dry, as an instance of DRIVE_MIX_RANGE: 100 %, because a rotary on an insert IS the sound (it replaces the cabinet) and an `fxReturn` wants it wet too (§3).",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 0.1,
+      "unit": "%",
+      "default": 100,
+      "defaultFrom": "desk"
+    }
+  },
+  "ROTARY_TRAVELS": {
+    "kind": "travels",
+    "doc": "The rotary's numeric travels, field → declaration: the ONE map the row's state, its bounds, its OPTIONS and its controller read (`speed` is a member set, ROTARY_SPEEDS, beside it).",
+    "fields": {
+      "hornSlowHz": {
+        "ref": "ROTARY_HORN_SLOW_RANGE"
+      },
+      "hornFastHz": {
+        "ref": "ROTARY_HORN_FAST_RANGE"
+      },
+      "drumSlowHz": {
+        "ref": "ROTARY_DRUM_SLOW_RANGE"
+      },
+      "drumFastHz": {
+        "ref": "ROTARY_DRUM_FAST_RANGE"
+      },
+      "accel": {
+        "ref": "ROTARY_ACCEL_RANGE"
+      },
+      "balance": {
+        "ref": "ROTARY_BALANCE_RANGE"
+      },
+      "mix": {
+        "ref": "ROTARY_MIX_RANGE"
+      }
+    }
+  },
+  "ROTARY_CROSSOVER_HZ": {
+    "kind": "scalar",
+    "doc": "The complementary split's low-pass corner, Hz: the Leslie 122's passive crossover.",
+    "unit": "Hz",
+    "value": 800
+  },
+  "ROTARY_BASE_MS": {
+    "kind": "scalar",
+    "doc": "The shortest Doppler read, ms — above the order-3 read's one-sample reach at every rate.",
+    "unit": "ms",
+    "value": 0.1
+  },
+  "ROTARY_HORN_DOPPLER_MS": {
+    "kind": "scalar",
+    "doc": "The horn's Doppler excursion `D_horn`, ms: a 0.15 m radius over 343 m/s.",
+    "unit": "ms",
+    "value": 0.44
+  },
+  "ROTARY_DRUM_DOPPLER_MS": {
+    "kind": "scalar",
+    "doc": "The drum's Doppler excursion `D_drum`, ms: its baffle turns over a fixed woofer.",
+    "unit": "ms",
+    "value": 0.29
+  },
+  "ROTARY_HORN_AM": {
+    "kind": "scalar",
+    "doc": "The horn's amplitude swing `m_horn` (a −6 dB directivity dip), a ratio.",
+    "unit": "",
+    "value": 0.5
+  },
+  "ROTARY_DRUM_AM": {
+    "kind": "scalar",
+    "doc": "The drum baffle's amplitude swing `m_drum`, a ratio.",
+    "unit": "",
+    "value": 0.3
+  },
+  "ROTARY_HORN_ACCEL_MS": {
+    "kind": "scalar",
+    "doc": "The horn rotor's speed-up time constant, ms (at `accel` 1).",
+    "unit": "ms",
+    "value": 330
+  },
+  "ROTARY_HORN_DECEL_MS": {
+    "kind": "scalar",
+    "doc": "The horn rotor's slow-down time constant, ms (at `accel` 1).",
+    "unit": "ms",
+    "value": 500
+  },
+  "ROTARY_DRUM_ACCEL_MS": {
+    "kind": "scalar",
+    "doc": "The drum rotor's speed-up time constant, ms (at `accel` 1).",
+    "unit": "ms",
+    "value": 1700
+  },
+  "ROTARY_DRUM_DECEL_MS": {
+    "kind": "scalar",
+    "doc": "The drum rotor's slow-down time constant, ms (at `accel` 1).",
+    "unit": "ms",
+    "value": 1800
+  },
+  "ROTARY_STOP_EPS": {
+    "kind": "scalar",
+    "doc": "Below this rate, Hz, a rotor coasting toward `stop` is snapped to exactly 0.",
+    "unit": "",
+    "value": 0.0001
+  },
+  "ROTARY_RING_FLOATS": {
+    "kind": "scalar",
+    "doc": "One inline ring per rotor per leg, floats — at least the 192 kHz need of the horn's sweep.",
+    "unit": "",
+    "value": 256
+  }
+}

package/data/kernels/tremolo.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "TREMOLO_RATE_RANGE": {
+    "kind": "travels",
+    "doc": "The tremolo's LFO rate (the catalogue row's 0.1..20 Hz); 4 Hz is the classic amp tremolo.",
+    "travel": {
+      "min": 0.1,
+      "max": 20,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 4,
+      "defaultFrom": "desk"
+    }
+  },
+  "TREMOLO_DEPTH_RANGE": {
+    "kind": "travels",
+    "doc": "The tremolo's modulation depth: the gain's trough is `1 − mix·depth`.",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 0.1,
+      "unit": "%",
+      "default": 50,
+      "defaultFrom": "desk"
+    }
+  },
+  "TREMOLO_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The tremolo's wet/dry, as an instance of DRIVE_MIX_RANGE: 100 %. The kernel folds the wet/dry into its one gain, so a strip tremolo IS the sound (as the rotary's mix 100 % is).",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 0.1,
+      "unit": "%",
+      "default": 100,
+      "defaultFrom": "desk"
+    }
+  },
+  "TREMOLO_TRAVELS": {
+    "kind": "travels",
+    "doc": "The tremolo's numeric travels, field → declaration: the ONE map the row's state, its bounds, its OPTIONS and its controller read (`mode` is a member set, TREMOLO_MODES, beside it).",
+    "fields": {
+      "rateHz": {
+        "ref": "TREMOLO_RATE_RANGE"
+      },
+      "depth": {
+        "ref": "TREMOLO_DEPTH_RANGE"
+      },
+      "mix": {
+        "ref": "TREMOLO_MIX_RANGE"
+      }
+    }
+  }
+}