fractal-midi 0.1.0-alpha.0

package/dist/axe-fx-iii/params.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Axe-Fx III parameter catalog.
+ *
+ * Auto-generated by
+ *   scripts/_research/generate-axefx3-params-from-catalog.ts
+ * from
+ *   samples/captured/decoded/ghidra-axeedit3-paramnames.json
+ * (Ghidra-mined Axe-Edit III v1.14.31 effect-type dispatcher
+ * FUN_140397a40 — Session 82), with AM4-derived display
+ * calibration layered on top (see
+ * `scripts/_research/axefx3-am4-overrides.ts`). DO NOT HAND-EDIT
+ * — re-run the generator to refresh.
+ *
+ * Coverage:
+ *   - 2216 parameters across 48 effect families.
+ *   - **2200/2200 (100%) calibration-eligible entries** carry a
+ *     non-`'unverified'` unit tag after the post-generation overlay
+ *     pass (`scripts/axe-fx-iii/apply-calibration-overlay.ts`).
+ *   - 16 entries remain `unit: 'unverified'` and are exempted by the
+ *     calibration acceptance gate because they are string-typed
+ *     (`_NAME`, `_LABEL1`..`_LABEL4`, `_MSG`) — the `Param` interface
+ *     has no `'string'` unit so the codec layer treats them as opaque.
+ *
+ * Tiered calibration provenance (in declaration order on each entry):
+ *       • Baseline (from generator):
+ *           - AM4 symbol-name join — `// inferred from AM4`. 236 entries.
+ *           - Universal Fractal convention (generator's suffix pass) —
+ *             `// inferred from Fractal convention`. 226 entries.
+ *           - AxeEdit III XML controlType — `// inferred from AxeEdit III XML controlType`.
+ *             1564 entries with unit but no range.
+ *       • Post-generation overlay (`apply-calibration-overlay.ts`):
+ *           - `// post-gen overlay: <reason>` — extended suffix table
+ *             closing the long-tail of `'unverified'` entries with
+ *             defensible Fractal-convention units. ~146 entries.
+ *
+ * Enum vocabularies (resolveEnumValues lookup):
+ *   - `src/axe-fx-iii/enumOverlay.ts` provides a runtime-joined enum
+ *     vocabulary layer combining AM4-verified shared tables (LFO
+ *     waveforms, tempo divisions, filter slopes, channel pickers),
+ *     universal Fractal binary toggles (OFF/ON, ENGAGED/BYPASSED), and
+ *     hand-curated III-specific entries. Each vocabulary tier carries
+ *     a `provenance` tag (`'am4-shared'` / `'fractal-convention'` /
+ *     `'iii-spec'`). Hardware-verification of III enum values is
+ *     user-driven via GitHub issue.
+ *
+ * Calibration sources (per-family inferred count):
+ *   CABINET=104, CHORUS=32, COMP=35, CONTROLLERS=136, CROSSOVER=15, DELAY=86, DISTORT=135, DYNDIST=12, ENHANCER=12, FC=8, FDBKRET=6, FILTER=37, FLANGER=55, FORMANT=12, FUZZ=43, GATE=19, GEQ=20, GLOBAL=228, INPUT=10, IRPLAYER=22, LOOPER=22, MEGATAP=34, MIDIBLOCK=10, MIXER=23, MOD=20, MULTICOMP=37, MULTIPLEXER=7, MULTITAP=116, OUTPUT=26, PEQ=33, PHASER=35, PITCH=112, PLEX=93, PRESET=51, RESONATOR=39, REVERB=71, RINGMOD=12, ROTARY=21, RTA=4, SYNTH=41, TENTAP=44, TONEMATCH=21, TREMOLO=22, VOCODER=67, VOLUME=13, WAH=25
+ *
+ * Inferred-from-AM4 caveat:
+ *   - AM4 is the closest hardware-verified analog Fractal device.
+ *     Same vendor, same naming convention, similar musical scope.
+ *     The inferred display range (e.g. reverb time 0.1..100 s,
+ *     drive 0..10 knob) is correct as a *display* convention —
+ *     this is what Fractal's UI shows for the knob across both
+ *     devices.
+ *   - The III's wire encoding for the displayed value is NOT
+ *     yet verified. AM4 packs values into normalized [0,1] Q15;
+ *     the III packs into a 16-bit linear field via packValue16.
+ *     Display↔wire conversion still requires III-side capture.
+ *   - Enum entries inherit `unit: 'enum'` from AM4 but DO NOT
+ *     ship AM4's enumValues table. III firmware adds reverb
+ *     types, amp models, etc. post-AM4 — copying AM4's vocabulary
+ *     verbatim would mislead the agent. The III's enum vocabulary
+ *     needs III-side Ghidra mining or hardware capture.
+ *
+ * Wire constraints (see ./setParam.ts):
+ *   - paramId is sent as a 14-bit septet pair → wire range is
+ *     0..16383. Catalog entries with paramId >= 65520 are
+ *     firmware-internal sentinels (e.g. *_SET_ALL, *_VAL_ALL)
+ *     and are NOT addressable via 0x02 SET_PARAMETER — they
+ *     will fail the encode14 range guard. They are retained in
+ *     this catalog as documentary entries because they show up
+ *     in the dispatcher tables; tooling that resolves a name to
+ *     a paramId should filter > 16383 before attempting a wire
+ *     write.
+ *
+ * Firmware-legacy overlays:
+ *   - (family, paramId) is NOT unique. Some families (notably
+ *     FLANGER) keep older symbol names alongside the current
+ *     ones at the same paramIds (e.g. `FLANGER_TYPE` and
+ *     `FLANGER_OLD_TYPE` both at paramId 0). The duplicates are
+ *     intentional — older firmware presets store under the
+ *     `_OLD_` symbols, while new writes use the current names.
+ *     The composite key `(family, name)` IS unique; use
+ *     `PARAM_BY_KEY` for stable lookup.
+ *
+ * 🟢 SET wire shape byte-verified Session 97 against 10 public
+ * captures: `fn=0x01` + sub-action `09 00` (typed-input), 23-byte
+ * envelope. NOT the pre-Session-97 `fn=0x02` II-port. Capture
+ * corpus + field layout: `docs/axefx3-set-parameter-captures.md`.
+ * 🟡 GET response shape still unverified — the `04 01`
+ * STATE_BROADCAST appears to be an AxeEdit-driven heartbeat poll,
+ * NOT a sync SET echo. See `docs/SYSEX-MAP-AXE-FX-III.md` §0x01.
+ */
+/**
+ * Display-unit tag for an Axe-Fx III parameter.
+ *
+ * `'unverified'` is the default for entries the generator could
+ * not infer (the AM4 has no matching parameter, or the III family
+ * has no AM4 analog). Other tags are AM4-derived display
+ * conventions — they describe the user-facing scale (dB, ms,
+ * knob_0_10, etc.) but NOT the III's wire encoding. Display↔wire
+ * conversion is still the caller's responsibility on the III
+ * until hardware verification lands.
+ */
+export type Unit = 'bipolar_percent' | 'count' | 'db' | 'degrees' | 'enum' | 'hz' | 'knob_0_10' | 'knob_0_20' | 'ms' | 'numeric' | 'percent' | 'pf' | 'ratio' | 'seconds' | 'semitones' | 'unverified';
+/** One entry in the Axe-Fx III parameter catalog. */
+export interface Param {
+    /**
+     * Effect family symbol (e.g. `'REVERB'`, `'DELAY'`, `'COMP'`).
+     * Sourced from the dispatcher's case → table-of-params mapping.
+     */
+    family: string;
+    /**
+     * Parameter ID within the family. Wire-encoded as a 14-bit
+     * septet pair in 0x02 SET_PARAMETER frames. Values >= 65520 are
+     * firmware-internal sentinels and NOT wire-addressable — see
+     * file-level header for details.
+     */
+    paramId: number;
+    /**
+     * Symbol name from Axe-Edit III's binary (e.g. `'REVERB_TYPE'`).
+     * Stable across firmware releases of the same generation.
+     */
+    name: string;
+    /**
+     * Human-readable display label from the AxeEdit III JUCE-BinaryData
+     * XML mining — the editor's knob caption (e.g. `'Drive'` for
+     * `DISTORT_DRIVE`, `'Reverb Time'` for `REVERB_TIME`). Populated
+     * for ~91% of catalog entries; absent for symbols the editor
+     * doesn't render (firmware-internal blocks, sentinel paramIds).
+     * Useful as LLM prompt context independent of unit/range.
+     */
+    displayLabel?: string;
+    /**
+     * Display unit tag. `'unverified'` until III hardware confirms
+     * the real shape; otherwise inferred from one of three sources
+     * (see file-level header for provenance — these are display
+     * conventions, not wire encodings).
+     */
+    unit: Unit;
+    /**
+     * Display range minimum. Populated for AM4-inferred entries
+     * (`// inferred from AM4` trailing comment), absent for
+     * `unit: 'unverified'` entries.
+     */
+    displayMin?: number;
+    /** Display range maximum. Same population rule as `displayMin`. */
+    displayMax?: number;
+    /**
+     * Optional non-linear scaling, AM4-inferred. `'log10'` for
+     * time / frequency knobs that span multiple decades. Absent
+     * for linear knobs or `'unverified'` entries.
+     */
+    scaling?: 'linear' | 'log10';
+}
+/**
+ * Flat catalog of every (family, paramId) entry mined from the
+ * Axe-Edit III dispatcher. Sorted by family-case-index ascending,
+ * then paramId ascending within each family, for byte-stable
+ * regeneration.
+ */
+export declare const PARAMS: readonly Param[];
+/**
+ * Lookup by family symbol. Each family's entry preserves the
+ * paramId-ascending order from `PARAMS`.
+ */
+export declare const PARAMS_BY_FAMILY: Readonly<Record<string, readonly Param[]>>;
+/**
+ * Lookup by `'FAMILY.NAME'` (the catalog's natural composite key).
+ * Example: `PARAM_BY_KEY['REVERB.REVERB_TYPE']` → the Reverb Type
+ * entry. Use this when callers reference a param by its symbolic
+ * name; use `PARAMS_BY_FAMILY[family]` when iterating a whole
+ * family.
+ */
+export declare const PARAM_BY_KEY: Readonly<Record<string, Param>>;
+/** Family symbols present in the catalog, in dispatcher-case order. */
+export declare const FAMILIES: readonly string[];
+//# sourceMappingURL=params.d.ts.map

package/dist/axe-fx-iii/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../src/axe-fx-iii/params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,IAAI,GAAG,iBAAiB,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,GAAG,WAAW,GAAG,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,CAAC;AAEvM,qDAAqD;AACrD,MAAM,WAAW,KAAK;IACpB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,IAAI,EAAE,IAAI,CAAC;IACX;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC9B;AAID;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,KAAK,EAyqElC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC,CAywEvE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAyqExD,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,QAAQ,EAAE,SAAS,MAAM,EAiDrC,CAAC"}