@openmixer/omx-contract 1.1.0 → 1.2.1

package/README.md

@@ -6,7 +6,8 @@ The FreeMixer declarations as data: what a value may be (a travel, a default, 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, and 1.1.0 adds the flanger, de-esser, phaser, rotary, tremolo and graphic EQ kernels.
+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
@@ -40,9 +41,9 @@ share/omx-contract` and `render --target ts --out test/golden/ts`; CI holds all
 
 ## Consuming it
 
-Pin one version (`omx-contract 1.1.0` in `.github/pins.txt`) and build against its renders, committing
+Pin one version (`omx-contract 1.2.1` 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.1.0 omx-contract`), else the release's npm tarball, unpacked, and
+(`pkg-config --exact-version=1.2.1 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/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/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/reverb.json

@@ -11,5 +11,140 @@
       "default": 100,
       "defaultFrom": "desk"
     }
+  },
+  "REVERB_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The REVERB's wet/dry. An insert keeps the dry signal (0.3); an `fxReturn` is wet-only (1), so the return carries only the effect. Both numbers live HERE and nowhere else: the row's `mix` limit, `ReverbController`'s seed and its fresh state read them through limitForKind.",
+    "travel": {
+      "min": 0,
+      "max": 1,
+      "step": 0,
+      "unit": "",
+      "default": 0.3,
+      "defaultFrom": "desk",
+      "byKind": {
+        "fxReturn": 1
+      }
+    }
+  },
+  "REVERB_SIZE_RANGE": {
+    "kind": "travels",
+    "doc": "The reverb's SIZE/DAMPING/WIDTH — each a NORMALIZED_RANGE instance with its own come-up value, matching `DEFAULT_REVERB_STATE`. Three separate constants rather than one shared default on `NORMALIZED_RANGE`: that range is the bare 0..1 REPRESENTATION, reused by fields across the whole console whose come-up values disagree (a fader position is not a reverb's damping), so a default belongs on the NAMED field, never on the shape it borrows.",
+    "travel": {
+      "min": 0,
+      "max": 1,
+      "step": 0,
+      "unit": "",
+      "default": 0.7,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_DAMPING_RANGE": {
+    "kind": "travels",
+    "doc": "The reverb's DAMPING — a NORMALIZED_RANGE instance with its own come-up value, matching `DEFAULT_REVERB_STATE`. Declared with SIZE and WIDTH (see REVERB_SIZE_RANGE for why each is a named constant rather than a default on the shared 0..1 shape).",
+    "travel": {
+      "min": 0,
+      "max": 1,
+      "step": 0,
+      "unit": "",
+      "default": 0.5,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_WIDTH_RANGE": {
+    "kind": "travels",
+    "doc": "The reverb's stereo WIDTH — a NORMALIZED_RANGE instance with its own come-up value, matching `DEFAULT_REVERB_STATE`. Declared with SIZE and DAMPING (see REVERB_SIZE_RANGE for why each is a named constant rather than a default on the shared 0..1 shape).",
+    "travel": {
+      "min": 0,
+      "max": 1,
+      "step": 0,
+      "unit": "",
+      "default": 1,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_PREDELAY_RANGE": {
+    "kind": "travels",
+    "doc": "The reverb's PRE-DELAY travel — the gap before the first reflection, in milliseconds. Declared here so the unit crosses with the bounds: a `finiteNumber(0, 100)` codec publishes `unit: ''`, and a surface binding that draws a millisecond control it cannot label. The panel knowing better than the wire is the wrong way round.",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 1,
+      "unit": "ms",
+      "default": 0,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_LOWCUT_RANGE": {
+    "kind": "travels",
+    "doc": "The reverb's LOW cut, as an instance of REVERB_CUT_RANGE — same bounds, its own come-up value. `0` reads as \"none\" (`mix_reverb.h`), which is also `DEFAULT_REVERB_STATE`'s seed, so a fresh reverb's low cut and its declared default are the same fact stated once. Split from REVERB_CUT_RANGE rather than adding `default` there: the low and high cut share ONE travel (the C imposes one constraint on both) but do NOT share one come-up value, and a `default` on the shared range could only be honest for one of the two fields that read it.",
+    "travel": {
+      "min": 0,
+      "max": 20000,
+      "step": 10,
+      "unit": "Hz",
+      "default": 0,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_HIGHCUT_RANGE": {
+    "kind": "travels",
+    "doc": "The reverb's HIGH cut, as an instance of REVERB_CUT_RANGE — same bounds, its own come-up value. The top of the travel reads as \"open\" (`mix_reverb.h`), matching `DEFAULT_REVERB_STATE`'s seed.",
+    "travel": {
+      "min": 0,
+      "max": 20000,
+      "step": 10,
+      "unit": "Hz",
+      "default": 20000,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_REVERSE_RANGE": {
+    "kind": "travels",
+    "doc": "REVERSE's MIRROR WINDOW — how long a slice of the wet is played backward, in milliseconds (`2026-07-15-native-delay-reverb.md`, Amendment 2026-09-17 §B). A DECLARED travel and never derived from `size`'s RT60: an RT60 of seconds cannot be buffered at 192 kHz, and a window silently clamped to fit is the silent-clamp defect. The ceiling is what `mix_reverb.h`'s pool budgets a ring for (`OMX_REVERB_REVERSE_MAX_MS`), so the console offers exactly the travel the kernel accepts — nothing wider, nothing narrower.",
+    "travel": {
+      "min": 50,
+      "max": 500,
+      "step": 10,
+      "unit": "ms",
+      "default": 300,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_HOLD_RANGE": {
+    "kind": "travels",
+    "doc": "GATED's HOLD — how long the wet stays at full level after the key falls away, in milliseconds. The Phil-Collins tail is cut where the operator puts the cut, so this is the control that decides the effect's length; `size` still decides what is being cut off.",
+    "travel": {
+      "min": 10,
+      "max": 2000,
+      "step": 10,
+      "unit": "ms",
+      "default": 120,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_RELEASE_RANGE": {
+    "kind": "travels",
+    "doc": "GATED's RELEASE — how long the held wet takes to reach zero, in milliseconds. A straight line down, short by design: a long release is a reverb tail again, which is the thing a gated reverb exists to remove.",
+    "travel": {
+      "min": 1,
+      "max": 500,
+      "step": 1,
+      "unit": "ms",
+      "default": 20,
+      "defaultFrom": "desk"
+    }
+  },
+  "REVERB_GATE_THRESHOLD_RANGE": {
+    "kind": "travels",
+    "doc": "GATED's ARM THRESHOLD — the level the reverb's own mono feed must reach to arm the hold, in dBFS. Declared, because the alternative is a hidden onset detector: the kernel compares `|input|` against exactly this number and nothing else.",
+    "travel": {
+      "min": -80,
+      "max": 0,
+      "step": 1,
+      "unit": "dBFS",
+      "default": -40,
+      "defaultFrom": "desk"
+    }
   }
 }

package/data/primitives.json

@@ -43,5 +43,79 @@
         "ref": "FDELAY_MOD_READ_ORDER"
       }
     }
+  },
+  "GATE_CONTINUOUS_TRAVELS": {
+    "kind": "travels",
+    "doc": "The gate's threshold, range, release and ratio as a plugin host draws them: GATE_LIMITS' bounds, units and defaults with no step. The console's row quantises these four to whole steps (1 dB, 10 ms, 1:1), and a travel whose step is 1 or more reads as an integer control; the omx-strip plugin has always offered them continuous, so it reads this table instead. Every number but the step is GATE_LIMITS', held equal by test/continuous-travels.test.mjs. Not rendered to C: no C reader needs a second spelling of the gate's bounds.",
+    "fields": {
+      "thresholdDb": {
+        "min": -80,
+        "max": 0,
+        "step": 0,
+        "unit": "dB",
+        "default": -40,
+        "defaultFrom": "desk"
+      },
+      "rangeDb": {
+        "min": -90,
+        "max": 0,
+        "step": 0,
+        "unit": "dB",
+        "default": -90,
+        "defaultFrom": "desk"
+      },
+      "releaseMs": {
+        "min": 0,
+        "max": 5000,
+        "step": 0,
+        "unit": "ms",
+        "default": 100,
+        "defaultFrom": "desk"
+      },
+      "ratio": {
+        "min": 1,
+        "max": 100,
+        "step": 0,
+        "unit": "",
+        "default": 16,
+        "defaultFrom": "desk"
+      }
+    }
+  },
+  "COMP_CONTINUOUS_TRAVELS": {
+    "kind": "travels",
+    "doc": "The compressor's threshold and release as a plugin host draws them: COMP_LIMITS' bounds, units and defaults with no step. The console's row quantises them to whole steps (1 dB, 10 ms), and a travel whose step is 1 or more reads as an integer control; the omx-strip plugin has always offered them continuous, so it reads this table instead. Every number but the step is COMP_LIMITS', held equal by test/continuous-travels.test.mjs. Not rendered to C: no C reader needs a second spelling of the compressor's bounds.",
+    "fields": {
+      "thresholdDb": {
+        "min": -60,
+        "max": 0,
+        "step": 0,
+        "unit": "dB",
+        "default": -18,
+        "defaultFrom": "desk"
+      },
+      "releaseMs": {
+        "min": 5,
+        "max": 3000,
+        "step": 0,
+        "unit": "ms",
+        "default": 200,
+        "defaultFrom": "desk"
+      }
+    }
+  },
+  "TRIM_TRAVELS": {
+    "kind": "travels",
+    "doc": "The digital input trim as a travel: openmixer's TRIM_RANGE (packages/declarations, -24..+24 dB in 0.1 dB steps, spelled minDb/maxDb/stepDb there and OMX_TRIM_RANGE_*_DB in omx-dsp's header), coming up at 0 dB, the trim a channel has when none is set. The omx-strip plugin's trim reads it. A table with the one field `trimDb`, the name the trim row and the plugin store; not rendered to C, which already spells TRIM_RANGE its own way.",
+    "fields": {
+      "trimDb": {
+        "min": -24,
+        "max": 24,
+        "step": 0.1,
+        "unit": "dB",
+        "default": 0,
+        "defaultFrom": "desk"
+      }
+    }
   }
 }