@hraness/dawg 0.5.0 → 0.6.1

package/core/fx.ts

@@ -12,7 +12,11 @@
  * under `track.fx.<name>` with every parameter stored once enabled.
  */
 
+import { MODAL_LANE_PARAMS, WIND_LANE_PARAMS } from "./resonators.ts";
 import { SYNTH_LANE_PARAMS } from "./synth.ts";
+import { STRING_LANE_PARAMS } from "./strings.ts";
+import { KEYS_LANE_PARAMS } from "./keys.ts";
+import { GRANULAR_LANE_PARAMS } from "./granular.ts";
 import {
   FxValidationError,
   normalizeParam,
@@ -48,9 +52,20 @@ export const FX_CHAIN = Object.freeze([
   "vowel",
   "crush",
   "distort",
+  // 0.6 guitar rig (stomp box, amp head with noise gate, speaker cabinet).
+  "stomp",
+  "head",
+  "cab",
+  // 0.6.1 shoegaze (src/audio/effects/gaze.ts): a held tremolo arm, the
+  // dominant note's feedback bloom, a volume swell; double (mono in, stereo
+  // out) runs where the chain turns stereo.
+  "wobble",
+  "bloom",
+  "swell",
   "tremolo",
   "compressor",
   "pan",
+  "double",
   "phaser",
   "chorus",
   "leslie",
@@ -323,6 +338,300 @@ export const FX_SPECS = Object.freeze({
       },
     },
   },
+  stomp: {
+    label: "stomp box",
+    doc: "guitar pedal before the amp: fuzz (Big Muff), face (Fuzz Face), od (Tube Screamer), rat, octave (Octavia); oversampled",
+    simple: ["type", "gain", "tone", "level"],
+    strudel: "(no Strudel equivalent; dawg guitar rig)",
+    params: {
+      type: {
+        kind: "enum",
+        values: ["fuzz", "face", "od", "rat", "octave"],
+        default: "od",
+        doc: "circuit: fuzz (Big Muff), face (Fuzz Face), od (Tube Screamer), rat (RAT), octave (Octavia)",
+      },
+      gain: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 5,
+        step: 0.25,
+        automate: true,
+        doc: "the pedal's gain / sustain / distortion knob, 0..10",
+      },
+      tone: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.5,
+        step: 0.05,
+        automate: true,
+        doc: "dark 0 .. bright 1",
+      },
+      level: {
+        kind: "number",
+        min: -24,
+        max: 12,
+        default: 0,
+        step: 0.5,
+        unit: "dB",
+        doc: "trim over a level-matched pedal (0 = bypass loudness)",
+      },
+      octave: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.7,
+        step: 0.05,
+        doc: "octave: blend of the octave-up (rectified) path",
+      },
+      mix: mix(1),
+    },
+  },
+  head: {
+    label: "amp head",
+    doc: "guitar amp: preamp stages, Yeh-Smith tone stack, power amp with sag, level-matched across types; optional noise gate",
+    simple: ["type", "gain", "bass", "mid", "treble"],
+    strudel: "(no Strudel equivalent; Strudel amp is linear gain)",
+    params: {
+      type: {
+        kind: "enum",
+        values: ["clean", "chime", "crunch", "lead", "high", "solid", "bass"],
+        default: "crunch",
+        doc: "clean (blackface), chime (AC30), crunch (plexi), lead (JCM800), high (modern high gain), solid (JC-120), bass (SVT)",
+      },
+      gain: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 5,
+        step: 0.25,
+        automate: true,
+        doc: "preamp gain 0..10 (level-matched: more gain, not more volume)",
+      },
+      bass: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 5,
+        step: 0.5,
+        doc: "tone stack bass 0..10",
+      },
+      mid: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 5,
+        step: 0.5,
+        doc: "tone stack mid 0..10",
+      },
+      treble: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 5,
+        step: 0.5,
+        doc: "tone stack treble 0..10",
+      },
+      presence: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 5,
+        step: 0.5,
+        doc: "power amp presence 0..10 (5 flat)",
+      },
+      master: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 5,
+        step: 0.25,
+        automate: true,
+        doc: "power amp drive 0..10",
+      },
+      sag: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.3,
+        step: 0.05,
+        optional: true,
+        doc: "power supply sag 0..1 (absent: the head type's own)",
+      },
+      gate: {
+        kind: "number",
+        min: -96,
+        max: 0,
+        default: -60,
+        step: 1,
+        unit: "dB",
+        optional: true,
+        doc: "noise gate threshold before the amp (absent: no gate)",
+      },
+      level: {
+        kind: "number",
+        min: -24,
+        max: 12,
+        default: 0,
+        step: 0.5,
+        unit: "dB",
+        doc: "output level after level matching",
+      },
+    },
+  },
+  cab: {
+    label: "speaker cabinet",
+    doc: "speaker cabinet and microphone (biquad model, no impulse response)",
+    simple: ["type", "mic", "mix"],
+    strudel: "(no Strudel equivalent; dawg guitar rig)",
+    params: {
+      type: {
+        kind: "enum",
+        values: ["1x12", "2x12", "4x12", "1x10", "open", "8x10", "1x15", "di"],
+        default: "2x12",
+        doc: "1x12, 2x12, 4x12, 1x10, open back, 8x10 and 1x15 bass, di (no speaker)",
+      },
+      mic: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.3,
+        step: 0.05,
+        doc: "microphone position: 0 centre (bright) .. 1 edge (dark)",
+      },
+      mix: mix(1),
+    },
+  },
+  wobble: {
+    label: "wobble",
+    doc: "held tremolo arm: slow seeded pitch wow and flutter of the whole track",
+    simple: ["depth", "rate", "drift"],
+    strudel: "(no Strudel equivalent; dawg shoegaze)",
+    params: {
+      depth: {
+        kind: "number",
+        min: 0,
+        max: 100,
+        default: 20,
+        step: 1,
+        unit: "c",
+        automate: true,
+        doc: "peak pitch deviation in cents",
+      },
+      rate: {
+        kind: "number",
+        min: 0.05,
+        max: 8,
+        default: 0.5,
+        step: 0.05,
+        unit: "Hz",
+        doc: "wobble rate",
+      },
+      drift: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.3,
+        step: 0.05,
+        doc: "0 periodic .. 1 wandering (seeded, so every render matches)",
+      },
+    },
+  },
+  bloom: {
+    label: "bloom",
+    doc: "feedback bloom: the top held note grows a singing harmonic",
+    simple: ["amount", "harm", "delay"],
+    strudel: "(no Strudel equivalent; dawg shoegaze)",
+    params: {
+      amount: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.5,
+        step: 0.05,
+        doc: "level of the feedback partial",
+      },
+      harm: {
+        kind: "number",
+        min: 1,
+        max: 4,
+        default: 2,
+        step: 1,
+        doc: "harmonic that feeds back: 1 the note, 2 its octave, 3 the fifth above",
+      },
+      delay: {
+        kind: "number",
+        min: 0,
+        max: 4,
+        default: 0.6,
+        step: 0.05,
+        unit: "s",
+        doc: "how long a note is held before it starts to feed back",
+      },
+      time: {
+        kind: "number",
+        min: 0.05,
+        max: 4,
+        default: 1,
+        step: 0.05,
+        unit: "s",
+        doc: "how fast the feedback grows",
+      },
+    },
+  },
+  swell: {
+    label: "swell",
+    doc: "volume swell: each strum fades in, no pick attack",
+    simple: ["time", "mix"],
+    strudel: "(no Strudel equivalent; dawg shoegaze)",
+    params: {
+      time: {
+        kind: "number",
+        min: 0.01,
+        max: 4,
+        default: 0.4,
+        step: 0.01,
+        unit: "s",
+        doc: "rise time after each onset",
+      },
+      mix: mix(1),
+    },
+  },
+  double: {
+    label: "double",
+    doc: "automatic double tracking: a seeded second take, spread left and right",
+    simple: ["time", "drift", "width"],
+    strudel: "(no Strudel equivalent; dawg shoegaze)",
+    params: {
+      time: {
+        kind: "number",
+        min: 5,
+        max: 60,
+        default: 22,
+        step: 1,
+        unit: "ms",
+        doc: "how late the second take plays",
+      },
+      drift: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 3,
+        step: 0.5,
+        unit: "ms",
+        doc: "how far the second take's timing wanders",
+      },
+      width: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.6,
+        step: 0.05,
+        doc: "0 centred .. 1 the two takes hard left and right",
+      },
+    },
+  },
   tremolo: {
     label: "tremolo",
     doc: "volume modulation",
@@ -834,6 +1143,14 @@ export const CORE_EFFECTS: readonly EffectName[] = Object.freeze([
   "reverb",
 ] as const);
 
+/** The 0.6.1 shoegaze stages (Effects > Shoegaze), in chain order. */
+export const SHOEGAZE_EFFECTS: readonly EffectName[] = Object.freeze([
+  "wobble",
+  "bloom",
+  "swell",
+  "double",
+] as const);
+
 export function isEffectName(value: unknown): value is EffectName {
   return (
     typeof value === "string" &&
@@ -903,12 +1220,21 @@ export function normalizeFx(input: unknown): TrackFx | undefined {
 }
 
 /** Automation lane name of an `fx` parameter, e.g. `distort-drive`. */
-export type FxLane = `${FxName | "reverb" | "synth"}-${string}`;
+export type FxLane =
+  `${FxName | "reverb" | "synth" | "string" | "keys" | "modal" | "grain" | "wind"}-${string}`;
 
 /** Every automatable `fx` parameter as `{ lane, effect, param, spec }`. */
 export const FX_LANES: readonly Readonly<{
   lane: FxLane;
-  effect: FxName | "reverb" | "synth";
+  effect:
+    | FxName
+    | "reverb"
+    | "synth"
+    | "string"
+    | "keys"
+    | "modal"
+    | "grain"
+    | "wind";
   param: string;
   spec: NumberParam;
 }>[] = Object.freeze([
@@ -936,6 +1262,53 @@ export const FX_LANES: readonly Readonly<{
       spec,
     }),
   ),
+  // String engine parameters (core/strings.ts), read at each note's onset.
+  ...STRING_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `string-${param}` as FxLane,
+      effect: "string" as const,
+      param,
+      spec,
+    }),
+  ),
+  // Modelled piano parameters (core/keys.ts), read at each note's onset.
+  ...KEYS_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `keys-${param}` as FxLane,
+      effect: "keys" as const,
+      param,
+      spec,
+    }),
+  ),
+  // Modal parameters (core/resonators.ts), read at each note's onset
+  // (`modal-motordepth` every 32-sample control tick).
+  ...MODAL_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `modal-${param}` as FxLane,
+      effect: "modal" as const,
+      param,
+      spec,
+    }),
+  ),
+  // Granular parameters (core/granular.ts, 0.6.1), read every 32 frames;
+  // grain-scoped ones are latched at each grain's onset.
+  ...GRANULAR_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `grain-${param}` as FxLane,
+      effect: "grain" as const,
+      param,
+      spec,
+    }),
+  ),
+  // Wind parameters (core/winds.ts), read every 32-sample control tick.
+  ...WIND_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `wind-${param}` as FxLane,
+      effect: "wind" as const,
+      param,
+      spec,
+    }),
+  ),
 ]);
 
 /**
@@ -973,6 +1346,14 @@ export const FX_PRESETS: Readonly<
       cutoff: 400,
       resonance: 0.4,
     },
+    wah: {
+      type: "bpf",
+      sync: 0.5,
+      depth: 2,
+      shape: "sine",
+      cutoff: 700,
+      resonance: 0.6,
+    },
   },
   vowel: { a: { vowel: "a" }, o: { vowel: "o" }, ee: { vowel: "i" } },
   crush: {
@@ -987,6 +1368,50 @@ export const FX_PRESETS: Readonly<
     fold: { drive: 5, type: "fold", tone: 7000, mix: 0.7 },
     shape: { drive: 5, type: "shape", tone: 9000 },
   },
+  stomp: {
+    muff: { type: "fuzz", gain: 7, tone: 0.5 },
+    face: { type: "face", gain: 6, tone: 0.5 },
+    screamer: { type: "od", gain: 5, tone: 0.5, level: 3 },
+    rat: { type: "rat", gain: 6, tone: 0.4 },
+    octavia: { type: "octave", gain: 6, tone: 0.6, octave: 0.8 },
+    boost: { type: "od", gain: 0, tone: 0.6, level: 6 },
+  },
+  head: {
+    blackface: { type: "clean", gain: 3, treble: 6 },
+    ac: { type: "chime", gain: 4, treble: 6 },
+    plexi: { type: "crunch", gain: 5 },
+    lead: { type: "lead", gain: 6, mid: 6 },
+    modern: { type: "high", gain: 7, bass: 6, mid: 3, treble: 7, gate: -55 },
+    jc: { type: "solid", gain: 2, treble: 6 },
+    svt: { type: "bass", gain: 4, bass: 6 },
+  },
+  cab: {
+    "1x12": { type: "1x12" },
+    "2x12": { type: "2x12" },
+    "4x12": { type: "4x12" },
+    open: { type: "open" },
+    "8x10": { type: "8x10" },
+    "1x15": { type: "1x15" },
+    di: { type: "di" },
+  },
+  wobble: {
+    glide: { depth: 35, rate: 0.4, drift: 0.4 },
+    tape: { depth: 12, rate: 0.8, drift: 0.6 },
+    seasick: { depth: 60, rate: 0.25, drift: 0.2 },
+  },
+  bloom: {
+    octave: { amount: 0.5, harm: 2, delay: 0.6, time: 1 },
+    fifth: { amount: 0.4, harm: 3, delay: 0.8, time: 1.2 },
+    ebow: { amount: 0.8, harm: 1, delay: 0.1, time: 0.6 },
+  },
+  swell: {
+    slow: { time: 0.8 },
+    violin: { time: 0.3 },
+  },
+  double: {
+    tight: { time: 12, drift: 1.5, width: 0.5 },
+    wide: { time: 28, drift: 3, width: 0.7 },
+  },
   tremolo: {
     gentle: { sync: 1, depth: 0.3, shape: "sine" },
     "eighth-chop": { sync: 0.5, depth: 0.9, shape: "square" },
@@ -1060,6 +1485,268 @@ export const FX_PRESETS: Readonly<
   },
 } satisfies Partial<Record<EffectName, Record<string, FxValues>>>);
 
+/** The guitar rig stages, in chain order: what `rig reset` clears. */
+export const RIG_STAGES = Object.freeze(["stomp", "head", "cab"] as const);
+export type RigStage = (typeof RIG_STAGES)[number];
+
+/**
+ * Whole guitar rigs (`rig <name>`): each sets the rig stages it names over
+ * their defaults and clears the ones it leaves out. A few also set one
+ * other effect (a wah, a spring-like reverb, a chorus) the sound needs.
+ */
+export const RIG_PRESETS: Readonly<
+  Record<string, Readonly<Partial<Record<FxName | "reverb", FxValues>>>>
+> = Object.freeze({
+  clean: {
+    head: { type: "clean", gain: 3, treble: 6 },
+    cab: { type: "1x12" },
+  },
+  crunch: { head: { type: "crunch", gain: 5 }, cab: { type: "4x12" } },
+  punk: {
+    head: { type: "crunch", gain: 7, mid: 6, master: 6 },
+    cab: { type: "4x12", mic: 0.2 },
+  },
+  ragged: {
+    stomp: { type: "face", gain: 6, tone: 0.6 },
+    head: { type: "chime", gain: 4 },
+    cab: { type: "2x12" },
+  },
+  lead: {
+    stomp: { type: "od", gain: 3, tone: 0.5, level: 3 },
+    head: { type: "lead", gain: 6, mid: 6 },
+    cab: { type: "4x12" },
+  },
+  metal: {
+    stomp: { type: "od", gain: 0, tone: 0.6, level: 6 },
+    head: { type: "high", gain: 7, bass: 6, mid: 3, treble: 7, gate: -55 },
+    cab: { type: "4x12", mic: 0.2 },
+  },
+  fuzz: {
+    stomp: { type: "fuzz", gain: 7, tone: 0.5 },
+    head: { type: "clean", gain: 4 },
+    cab: { type: "2x12" },
+  },
+  octave: {
+    stomp: { type: "octave", gain: 6, tone: 0.6, octave: 0.8 },
+    head: { type: "clean", gain: 3 },
+    cab: { type: "1x12" },
+  },
+  funk: {
+    head: { type: "clean", gain: 2, treble: 7, presence: 6 },
+    cab: { type: "2x12" },
+    autofilter: {
+      type: "bpf",
+      sync: 0,
+      rate: 0.01,
+      depth: 0,
+      follow: 3,
+      cutoff: 500,
+      resonance: 0.6,
+    },
+  },
+  wah: {
+    head: { type: "crunch", gain: 4 },
+    cab: { type: "2x12" },
+    autofilter: {
+      type: "bpf",
+      sync: 0.5,
+      depth: 2,
+      shape: "sine",
+      cutoff: 700,
+      resonance: 0.6,
+    },
+  },
+  bachata: {
+    head: { type: "clean", gain: 2, mid: 6, treble: 7 },
+    cab: { type: "1x12", mic: 0.2 },
+    chorus: { rate: 0.8, depth: 0.25, mix: 0.3 },
+  },
+  spring: {
+    head: { type: "clean", gain: 3, treble: 6 },
+    cab: { type: "open" },
+    reverb: { mix: 0.3, size: 0.35, fade: 1.5, predelay: 0, dim: 3500 },
+  },
+  bassdrive: {
+    stomp: { type: "od", gain: 4, tone: 0.5, mix: 0.6 },
+    head: { type: "bass", gain: 4 },
+    cab: { type: "8x10" },
+  },
+  reese: {
+    stomp: { type: "rat", gain: 3, tone: 0.3, mix: 0.5 },
+    head: { type: "bass", gain: 6, master: 6 },
+    cab: { type: "1x15" },
+  },
+  jangle: {
+    head: { type: "chime", gain: 3, treble: 7 },
+    cab: { type: "2x12", mic: 0.2 },
+    compressor: { threshold: -20, ratio: 4, attack: 0.01, release: 0.15 },
+    // 0.6.1: the double-tracked jangle of a twelve-string record. A stored
+    // 0.6.0 jangle (no double) keeps rendering as it was; `rig jangle` again
+    // adds it. The SDK's rig("jangle") keeps its 0.6.0 stages (see
+    // RIG_ADDED), so the printer writes this double out explicitly.
+    double: { time: 12, drift: 1.5, width: 0.5 },
+  },
+  alt: {
+    stomp: { type: "rat", gain: 6, tone: 0.4 },
+    head: { type: "crunch", gain: 4 },
+    cab: { type: "4x12" },
+  },
+  // 0.6.1 shoegaze rigs (src/audio/effects/gaze.ts): fuzz into a held
+  // tremolo arm, a feedback bloom, doubled takes and a long wash.
+  shoegaze: {
+    stomp: { type: "fuzz", gain: 7, tone: 0.45 },
+    head: { type: "chime", gain: 4 },
+    cab: { type: "2x12" },
+    wobble: { depth: 25, rate: 0.4, drift: 0.4 },
+    bloom: { amount: 0.4, harm: 2, delay: 0.6, time: 1 },
+    double: { time: 18, drift: 2.5, width: 0.4 },
+    postgain: { gain: 0.86 },
+    reverb: { mix: 0.35, size: 0.9, fade: 4, predelay: 0.02, dim: 6000 },
+  },
+  glide: {
+    stomp: { type: "face", gain: 5, tone: 0.5 },
+    head: { type: "clean", gain: 4, treble: 5 },
+    cab: { type: "2x12" },
+    wobble: { depth: 35, rate: 0.4, drift: 0.4 },
+    postgain: { gain: 0.8 },
+    reverb: { mix: 0.35, size: 0.7, fade: 2.5, predelay: 0.01, dim: 6000 },
+  },
+  dreampop: {
+    head: { type: "clean", gain: 2, treble: 6 },
+    cab: { type: "1x12" },
+    chorus: { rate: 0.6, depth: 0.3, mix: 0.35 },
+    double: { time: 14, drift: 2, width: 0.4 },
+    postgain: { gain: 1.45 },
+    reverb: { mix: 0.4, size: 0.85, fade: 5, predelay: 0.03, dim: 7000 },
+  },
+  swell: {
+    head: { type: "clean", gain: 3, treble: 5 },
+    cab: { type: "1x12" },
+    swell: { time: 0.5 },
+    postgain: { gain: 1.25 },
+    reverb: { mix: 0.45, size: 0.8, fade: 4, predelay: 0.02, dim: 6500 },
+  },
+  ebow: {
+    stomp: { type: "od", gain: 3, tone: 0.5, level: 3 },
+    head: { type: "lead", gain: 5, mid: 6 },
+    cab: { type: "4x12" },
+    swell: { time: 0.25 },
+    bloom: { amount: 0.8, harm: 1, delay: 0.1, time: 0.6 },
+  },
+});
+
+/**
+ * Effects a rig preset gained after SDK `rig(name)` was fixed. `rig(name)`
+ * leaves them out, so an older song.ts spreading `...rig("jangle")` keeps
+ * its sound; the printer writes them next to the spread, and a stored
+ * track with or without them still reads as that rig.
+ */
+export const RIG_ADDED: Readonly<Record<string, readonly FxName[]>> =
+  Object.freeze({ jangle: Object.freeze(["double"] as FxName[]) });
+
+export function isRigPreset(name: string): boolean {
+  return Object.prototype.hasOwnProperty.call(RIG_PRESETS, name);
+}
+
+/**
+ * `fx` with rig preset `name` applied: rig stages it leaves out are
+ * removed, every stage it names is filled over its defaults, and other
+ * effects keep their values. `"reset"` removes the rig. A preset's track
+ * effect (the `spring` reverb) is not part of `fx`: see `rigReverb`.
+ */
+export function applyRigPreset(
+  fx: TrackFx | undefined,
+  name: string,
+): TrackFx | undefined {
+  const out: Record<string, unknown> = { ...(fx ?? {}) };
+  for (const stage of RIG_STAGES) delete out[stage];
+  // A previous rig's companion (funk's envelope filter, jangle's
+  // compressor…) goes with it, unless the user has changed it since.
+  for (const [effect, values] of Object.entries(out))
+    if (isRigCompanion(effect, values)) delete out[effect];
+  if (name !== "reset") {
+    if (!isRigPreset(name))
+      throw new FxValidationError(
+        `unknown rig "${name}" (rigs: ${Object.keys(RIG_PRESETS).join(", ")})`,
+      );
+    for (const [effect, values] of Object.entries(RIG_PRESETS[name]!))
+      if (isFxName(effect)) out[effect] = values;
+  }
+  return normalizeFx(out);
+}
+
+/** Normalized companion effects (not stages, not reverb) of every rig. */
+let companions: Map<string, string[]> | undefined;
+
+/** True when `values` is exactly what some rig preset writes for `effect`. */
+function isRigCompanion(effect: string, values: unknown): boolean {
+  if ((RIG_STAGES as readonly string[]).includes(effect)) return false;
+  if (!companions) {
+    companions = new Map();
+    for (const preset of Object.values(RIG_PRESETS))
+      for (const [name, raw] of Object.entries(preset)) {
+        if (!isFxName(name) || (RIG_STAGES as readonly string[]).includes(name))
+          continue;
+        const normal = normalizeFx({ [name]: raw })?.[name];
+        const list = companions.get(name) ?? [];
+        list.push(JSON.stringify(normal));
+        companions.set(name, list);
+      }
+  }
+  return companions.get(effect)?.includes(JSON.stringify(values)) ?? false;
+}
+
+/** True when `reverb` is exactly the track reverb some rig preset sets. */
+export function isRigReverb(reverb: unknown): boolean {
+  if (reverb === undefined) return false;
+  const json = JSON.stringify(reverb);
+  return Object.keys(RIG_PRESETS).some(
+    (name) => rigReverb(name) && JSON.stringify(rigReverb(name)) === json,
+  );
+}
+
+/** The track reverb a rig preset sets (spring), if any. */
+export function rigReverb(name: string): FxValues | undefined {
+  if (!isRigPreset(name)) return undefined;
+  const values = (RIG_PRESETS[name] as Record<string, FxValues | undefined>)
+    .reverb;
+  return values === undefined
+    ? undefined
+    : normalizeParams(TRACK_EFFECT_SPECS.reverb.params, values, "reverb");
+}
+
+/**
+ * The rig preset whose stages and companion effects `fx` matches exactly,
+ * if any (other effects may be present too).
+ */
+export function rigPresetOf(fx: TrackFx | undefined): string | undefined {
+  if (!fx || !RIG_STAGES.some((stage) => fx[stage])) return undefined;
+  for (const name of Object.keys(RIG_PRESETS)) {
+    const want: Partial<Record<FxName, FxValues>> = {
+      ...(applyRigPreset(undefined, name) ?? {}),
+    };
+    for (const added of RIG_ADDED[name] ?? []) delete want[added];
+    const keys = new Set<string>([...RIG_STAGES, ...Object.keys(want)]);
+    if (
+      [...keys].every(
+        (key) =>
+          JSON.stringify(fx[key as FxName]) ===
+          JSON.stringify(want[key as FxName]),
+      )
+    )
+      return name;
+  }
+  return undefined;
+}
+
+/** The effects of `fx` a printed `...rig(name)` stands for. */
+export function rigPresetKeys(name: string): readonly FxName[] {
+  const added = RIG_ADDED[name] ?? [];
+  return Object.keys(RIG_PRESETS[name] ?? {}).filter(
+    (key): key is FxName => isFxName(key) && !added.includes(key),
+  );
+}
+
 export function effectPresetNames(effect: EffectName): readonly string[] {
   return Object.keys(FX_PRESETS[effect] ?? {});
 }