@hraness/dawg 0.5.0 → 0.6.0

package/src/commands/keys.ts

@@ -0,0 +1,353 @@
+/**
+ * The modelled piano commands (0.6 keys lane, `core/keys.ts`):
+ *
+ *   piano                         the focused track becomes the modelled grand
+ *   piano <preset>                grand ballad upright felt lofi honkytonk prepared
+ *   grand | upright | felt …      the same, by the preset word alone
+ *   keys                          list this track's piano settings
+ *   keys preset <name>            load a preset (instrument, keys and its effects)
+ *   keys <param> <value> […]      set parameters (hardness 0.4 decay 1.5 …)
+ *   keys <param> off              unset one parameter (back to the preset's)
+ *   keys reset                    the family's own sound (`keys: {}`),
+ *                                 dropping the preset's unedited effects
+ *
+ * Every new write of `piano` stores `instrument: "grand"` with `keys`; a
+ * stored legacy `instrument: "piano"` is never rewritten unless asked. Each
+ * command is one `updateTrack` revision and one undo step.
+ */
+import { FxValidationError } from "../../core/params.ts";
+import {
+  KEYS_PARAMS,
+  KEYS_PRESETS,
+  KEYS_SIMPLE,
+  isKeysPreset,
+  isPianoFamily,
+  keysParamName,
+  normalizeKeys,
+  pianoWrite,
+  type TrackKeys,
+} from "../../core/keys.ts";
+import {
+  createScore,
+  ScoreValidationError,
+  updateTrack,
+  type TrackPatch,
+  type TrackScore,
+} from "../../core/score.ts";
+import { parseParamValue } from "./fx.ts";
+
+export type KeysCommand =
+  | { type: "keys-list" }
+  | { type: "keys-presets" }
+  | { type: "keys-reset" }
+  | { type: "keys-preset"; preset: string }
+  | {
+      type: "keys-set";
+      /** `null` unsets a parameter. */
+      values: Readonly<Record<string, number | string | null>>;
+    };
+
+/** The words that start a keys command (registered with /help). */
+export const KEYS_COMMAND_WORDS = Object.freeze([
+  "keys",
+  "piano",
+  ...Object.keys(KEYS_PRESETS).filter((name) => name !== "lofi"),
+]);
+
+export function parseKeysCommand(prompt: string): KeysCommand | undefined {
+  if (prompt.length > 1_024) return undefined;
+  let words = prompt.trim().toLowerCase().split(/\s+/);
+  // `instrument piano` / `sound grand`: the generic instrument command with
+  // a keys word is a new write, so it stores the modelled piano.
+  if (
+    words.length === 2 &&
+    ["instrument", "sound", "voice"].includes(words[0]!) &&
+    pianoWrite(words[1]!)
+  )
+    words = [words[1]!];
+  const head = words[0] ?? "";
+  // `piano`, `piano <preset>`, and a bare preset word (`grand`, `felt`).
+  if (head === "piano" || head === "uprightpiano" || head === "feltpiano") {
+    if (words.length === 1)
+      return { type: "keys-preset", preset: pianoWrite(head)!.preset! };
+    return words.length === 2 && isKeysPreset(words[1]!)
+      ? { type: "keys-preset", preset: words[1]! }
+      : undefined;
+  }
+  if (head !== "keys") {
+    if (words.length === 1 && isKeysPreset(head) && head !== "lofi")
+      return { type: "keys-preset", preset: head };
+    if (words.length === 2 && isKeysPreset(head) && words[1] === "piano")
+      return { type: "keys-preset", preset: head };
+    return undefined;
+  }
+  if (words.length === 1) return { type: "keys-list" };
+  const rest = words.slice(1);
+  if (rest.length === 1 && (rest[0] === "reset" || rest[0] === "off"))
+    return { type: "keys-reset" };
+  if (rest.length === 1 && rest[0] === "presets")
+    return { type: "keys-presets" };
+  if (rest[0] === "preset")
+    return rest.length === 2 && isKeysPreset(rest[1]!)
+      ? { type: "keys-preset", preset: rest[1]! }
+      : rest.length === 1
+        ? { type: "keys-presets" }
+        : undefined;
+  if (rest.length === 1 && isKeysPreset(rest[0]!))
+    return { type: "keys-preset", preset: rest[0]! };
+  if (rest.length % 2 !== 0) return undefined;
+  const values: Record<string, number | string | null> = {};
+  for (let index = 0; index < rest.length; index += 2) {
+    const name = keysParamName(rest[index]!);
+    if (!name) return undefined;
+    const word = rest[index + 1]!;
+    if (word === "off" || word === "unset") {
+      values[name] = null;
+      continue;
+    }
+    const value = parseParamValue(KEYS_PARAMS[name]!, word);
+    if (value === undefined || typeof value === "boolean") return undefined;
+    values[name] = value as number | string;
+  }
+  return { type: "keys-set", values };
+}
+
+export function describeKeys(keys: TrackKeys | undefined): string {
+  if (!keys) return "off";
+  const entries = Object.entries(keys).filter(([key]) => key !== "preset");
+  const parts = [
+    ...(keys.preset ? [`preset ${keys.preset}`] : []),
+    ...entries.map(([key, value]) => `${key} ${String(value)}`),
+  ];
+  return parts.length > 0 ? parts.join(" · ") : "defaults";
+}
+
+export type KeysResult = Readonly<{
+  ok: boolean;
+  message: string;
+  next?: TrackScore;
+  kind?: string;
+  payload?: Record<string, unknown>;
+}>;
+
+/** One line per preset for `keys presets`, /help and the agent prompt. */
+export function keysPresetLines(): string[] {
+  return Object.entries(KEYS_PRESETS).map(
+    ([name, preset]) => `${name} · ${preset.doc} · ${preset.styles}`,
+  );
+}
+
+type PresetTrack = Pick<
+  TrackScore["tracks"][number],
+  "fx" | "keys" | "filter" | "reverb"
+>;
+
+/** A preset's effects as the score stores them (defaults filled in). */
+const storedPresetFx = new Map<string, Track>();
+type Track = TrackScore["tracks"][number];
+function presetEffects(preset: string): Track | undefined {
+  if (storedPresetFx.has(preset)) return storedPresetFx.get(preset);
+  const write = pianoWrite(preset);
+  const track = write
+    ? createScore({
+        tracks: [
+          {
+            id: "p",
+            name: "p",
+            instrument: write.instrument,
+            ...(write.filter ? { filter: write.filter } : {}),
+            ...(write.fx ? { fx: write.fx } : {}),
+            ...(write.reverb ? { reverb: write.reverb } : {}),
+          },
+        ],
+      }).tracks[0]
+    : undefined;
+  if (track) storedPresetFx.set(preset, track);
+  return track;
+}
+
+/** True when `stored` still equals the preset's stored value. */
+function unchanged(stored: unknown, preset: unknown): boolean {
+  return (
+    stored !== undefined &&
+    preset !== undefined &&
+    JSON.stringify(stored) === JSON.stringify(preset)
+  );
+}
+
+/**
+ * Clears the effects the track's current preset brought (its filter, fx
+ * entries and reverb) while they still hold the preset's values, so moving
+ * between presets or resetting never piles them up. Effects the user has
+ * since edited stay.
+ */
+export function keysPresetClear(track: PresetTrack): TrackPatch {
+  const name = track.keys?.preset;
+  const old = typeof name === "string" ? presetEffects(name) : undefined;
+  if (!old) return {};
+  const patch: {
+    filter?: null;
+    reverb?: null;
+    fx?: TrackPatch["fx"];
+  } = {};
+  if (old.filter && unchanged(track.filter, old.filter)) patch.filter = null;
+  if (old.reverb && unchanged(track.reverb, old.reverb)) patch.reverb = null;
+  if (old.fx && track.fx) {
+    const fx: Record<string, unknown> = { ...track.fx };
+    let removed = false;
+    for (const [effect, params] of Object.entries(old.fx))
+      if (unchanged(fx[effect], params)) {
+        delete fx[effect];
+        removed = true;
+      }
+    if (removed)
+      patch.fx = Object.keys(fx).length > 0 ? (fx as TrackPatch["fx"]) : null;
+  }
+  return patch;
+}
+
+/**
+ * The track patch for a preset write (instrument, keys, preset effects),
+ * first clearing the effects the previous preset brought.
+ */
+export function keysPresetPatch(
+  track: PresetTrack,
+  preset: string,
+): TrackPatch {
+  const write = pianoWrite(preset)!;
+  const clear = keysPresetClear(track);
+  const fx = "fx" in clear ? (clear.fx ?? undefined) : track.fx;
+  return {
+    ...clear,
+    instrument: write.instrument,
+    keys: write.keys,
+    ...(write.filter ? { filter: write.filter } : {}),
+    ...(write.fx
+      ? { fx: { ...(fx ?? {}), ...write.fx } as TrackPatch["fx"] }
+      : {}),
+    ...(write.reverb ? { reverb: write.reverb } : {}),
+  };
+}
+
+export function applyKeysCommand(
+  score: TrackScore,
+  trackId: string,
+  command: KeysCommand,
+): KeysResult {
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return { ok: false, message: `no track · ${trackId}` };
+  if (command.type === "keys-presets")
+    return {
+      ok: true,
+      message: `keys presets · ${Object.keys(KEYS_PRESETS).join(" ")}`,
+    };
+  const piano = isPianoFamily(track.instrument);
+  if (command.type === "keys-list")
+    return {
+      ok: true,
+      message: piano
+        ? `keys · ${track.instrument} · ${describeKeys(track.keys)} · basics ${KEYS_SIMPLE.join(" ")}`
+        : `keys · ${trackId} is ${track.instrument}; type piano (or grand upright felt honkytonk prepared) for the modelled piano`,
+    };
+  if (track.sampler && command.type !== "keys-preset")
+    return {
+      ok: false,
+      message: `keys · ${trackId} is a sampler track; type piano to make it a modelled piano`,
+    };
+  let patch: TrackPatch;
+  if (command.type === "keys-preset") {
+    patch = {
+      ...keysPresetPatch(track, command.preset),
+      ...(track.sampler ? { sampler: null } : {}),
+      ...(track.synth ? { synth: null } : {}),
+    };
+  } else if (!piano) {
+    // `keys` is also the legacy synth sound (`instrument keys`): name both
+    // ways out.
+    const keysSynth = track.instrument === "keys";
+    const [first] = Object.keys(
+      command.type === "keys-set" ? command.values : {},
+    );
+    return {
+      ok: false,
+      message: keysSynth
+        ? `keys · keys shapes the modelled piano; ${trackId} is the keys synth: use synth ${first ?? "decay"} …, or type piano`
+        : `keys · ${trackId} is ${track.instrument}; type piano first (keys shapes the modelled piano)`,
+    };
+  } else if (command.type === "keys-reset") {
+    // The family's own sound: the preset and the effects it brought go.
+    patch = { ...keysPresetClear(track), keys: {} };
+  } else {
+    const keys: Record<string, unknown> = { ...(track.keys ?? {}) };
+    for (const [key, value] of Object.entries(command.values)) {
+      if (value === null) delete keys[key];
+      else keys[key] = value;
+    }
+    try {
+      patch = { keys: normalizeKeys(keys) ?? {} };
+    } catch (error) {
+      if (error instanceof FxValidationError)
+        return { ok: false, message: `keys · ${error.message}` };
+      throw error;
+    }
+  }
+  let next: TrackScore;
+  try {
+    next = updateTrack(score, trackId, patch);
+  } catch (error) {
+    if (
+      error instanceof ScoreValidationError ||
+      error instanceof FxValidationError
+    )
+      return { ok: false, message: `keys · ${error.message}` };
+    throw error;
+  }
+  const stored = next.tracks.find((candidate) => candidate.id === trackId)!;
+  const extras =
+    command.type === "keys-preset"
+      ? [
+          ...(patch.reverb ? ["reverb"] : []),
+          ...(patch.filter ? ["filter"] : []),
+          ...Object.keys(pianoWrite(command.preset)?.fx ?? {}),
+        ]
+      : [];
+  return {
+    ok: true,
+    message:
+      command.type === "keys-preset"
+        ? `keys · ${stored.instrument} · preset ${command.preset} · ${KEYS_PRESETS[command.preset]!.doc}${extras.length > 0 ? ` · with ${extras.join(" ")}` : ""}`
+        : `keys · ${stored.instrument} · ${describeKeys(stored.keys)}`,
+    next,
+    kind: "score.keys",
+    payload: {
+      trackId,
+      instrument: stored.instrument,
+      keys: stored.keys ?? null,
+    },
+  };
+}
+
+/**
+ * The fields a new track named after a piano word starts with
+ * (`/track piano` → the modelled grand); empty for any other name. `lofi`
+ * is left out: it also names a drum kit and pattern.
+ */
+export function newPianoTrack(name: string): {
+  instrument?: string;
+  keys?: TrackKeys;
+  filter?: TrackPatch["filter"];
+  fx?: TrackPatch["fx"];
+  reverb?: TrackPatch["reverb"];
+} {
+  const word = name.toLowerCase();
+  if (word === "lofi") return {};
+  const write = pianoWrite(word);
+  if (!write) return {};
+  return {
+    instrument: write.instrument,
+    keys: write.keys,
+    ...(write.filter ? { filter: write.filter } : {}),
+    ...(write.fx ? { fx: write.fx } : {}),
+    ...(write.reverb ? { reverb: write.reverb } : {}),
+  };
+}

package/src/commands/modal.ts

@@ -0,0 +1,247 @@
+/**
+ * The `modal` prompt command (0.6): modal percussion on the focused track
+ * (core/resonators.ts). The menu and the `set_modal` agent tool build the
+ * same edits.
+ *
+ *   modal                              show the track's preset and overrides
+ *   modal <preset>                     play a preset: marimba vibes xylophone
+ *                                      glock celesta chimes kalimba mbira
+ *                                      steelpan bowl gong timpani (and the
+ *                                      aliases vibraphone glockenspiel
+ *                                      tubular thumbpiano gongageng)
+ *   modal preset <name>                the same, spelled out
+ *   modal mallet <yarn|cord|rubber|plastic|brass>
+ *   modal <param> <value> [<param> <value>…]   hardness 0.8, ring 3 …
+ *   modal <param> off                  back to the preset's value
+ *   modal reset                        clear overrides (keep the preset)
+ *   modal off                          back to the legacy marimba voice
+ *   modal list | presets modal         the presets with one-line characters
+ *
+ * Any edit turns the track into a modal track (`instrument "modal"`); the
+ * legacy `marimba` tone is untouched until then. One `updateTrack` revision
+ * and one undo step per command.
+ */
+import { FxValidationError } from "../../core/params.ts";
+import {
+  DEFAULT_MODAL_PRESET,
+  MODAL_INSTRUMENT,
+  MODAL_PARAMS,
+  MODAL_PRESETS,
+  MODAL_PRESET_NAMES,
+  MODAL_SIMPLE,
+  modalParamName,
+  modalPresetFor,
+  normalizeModal,
+  type TrackModal,
+} from "../../core/resonators.ts";
+import {
+  ScoreValidationError,
+  updateTrack,
+  type TrackScore,
+} from "../../core/score.ts";
+import { parseParamValue } from "./fx.ts";
+
+export type ModalCommand =
+  | { type: "modal-show" }
+  | { type: "modal-list" }
+  | { type: "modal-reset" }
+  | { type: "modal-off" }
+  | { type: "modal-preset"; preset: string }
+  | { type: "modal-usage"; message: string }
+  | {
+      type: "modal-set";
+      /** `null` returns a parameter to the preset's value. */
+      values: Readonly<Record<string, number | string | null>>;
+    };
+
+/** The voice `modal off` returns a track to: the legacy marimba tone. */
+export const MODAL_OFF_INSTRUMENT = "marimba";
+
+export const MODAL_USAGE =
+  "modal <preset> | modal <body> | modal <param> <value> | modal mallet <name> | modal reset | modal off | modal presets";
+
+function rangeOf(name: string): string {
+  const spec = MODAL_PARAMS[name]!;
+  if (spec.kind === "number") return `${name} is ${spec.min}..${spec.max}`;
+  if (spec.kind === "enum") return `${name} is one of ${spec.values.join(" ")}`;
+  return name;
+}
+
+export function parseModalCommand(prompt: string): ModalCommand | undefined {
+  const words = prompt.trim().toLowerCase().split(/\s+/);
+  if (words[0] === "presets" && words[1] === "modal" && words.length === 2)
+    return { type: "modal-list" };
+  if (words[0] !== "modal") return undefined;
+  if (words.length === 1) return { type: "modal-show" };
+  if (prompt.length > 512) return undefined;
+  const rest = words.slice(1);
+  if (rest.length === 1 && rest[0] === "reset") return { type: "modal-reset" };
+  if (rest.length === 1 && rest[0] === "off") return { type: "modal-off" };
+  if (rest.length === 1 && (rest[0] === "list" || rest[0] === "presets"))
+    return { type: "modal-list" };
+  if (rest[0] === "preset") {
+    const preset = rest.length === 2 ? modalPresetFor(rest[1]!) : undefined;
+    return preset
+      ? { type: "modal-preset", preset }
+      : {
+          type: "modal-usage",
+          message: `modal preset is one of ${MODAL_PRESET_NAMES.join(" ")}`,
+        };
+  }
+  if (rest.length === 1) {
+    const preset = modalPresetFor(rest[0]!);
+    if (preset) return { type: "modal-preset", preset };
+    // A body word (saron, kempul, bonang, gender ...) sets the body: the
+    // gamelan presets come later, the bodies already ship.
+    const body = MODAL_PARAMS.body;
+    if (body?.kind === "enum" && body.values.includes(rest[0]!))
+      return { type: "modal-set", values: { body: rest[0]! } };
+    return { type: "modal-usage", message: MODAL_USAGE };
+  }
+  if (rest.length % 2 !== 0)
+    return { type: "modal-usage", message: MODAL_USAGE };
+  const values: Record<string, number | string | null> = {};
+  for (let index = 0; index < rest.length; index += 2) {
+    const name = modalParamName(rest[index]!);
+    if (!name)
+      return {
+        type: "modal-usage",
+        message: `modal has no parameter ${rest[index]!.slice(0, 24)} · ${MODAL_SIMPLE.join(" ")} …`,
+      };
+    const word = rest[index + 1]!;
+    if (word === "off" || word === "unset") {
+      values[name] = null;
+      continue;
+    }
+    const value = parseParamValue(MODAL_PARAMS[name]!, word);
+    if (value === undefined || typeof value === "boolean")
+      return { type: "modal-usage", message: rangeOf(name) };
+    values[name] = value;
+  }
+  return { type: "modal-set", values };
+}
+
+/** `preset vibes · hardness 0.6 · ring 3`, overrides in canonical order. */
+export function describeModal(modal: TrackModal | undefined): string {
+  if (!modal) return "not a modal track";
+  const preset = modal.preset ?? DEFAULT_MODAL_PRESET;
+  const overrides = Object.entries(modal)
+    .filter(([key]) => key !== "preset")
+    .map(([key, value]) => `${key} ${value}`);
+  return [`preset ${preset}`, ...overrides].join(" · ");
+}
+
+/** One line per preset, for `modal list` and the agent brief. */
+export function modalListLines(): string[] {
+  return MODAL_PRESET_NAMES.map(
+    (name) => `${name.padEnd(10)} ${MODAL_PRESETS[name].doc}`,
+  );
+}
+
+export type ModalResult = Readonly<{
+  ok: boolean;
+  message: string;
+  next?: TrackScore;
+  kind?: string;
+  payload?: Record<string, unknown>;
+}>;
+
+/**
+ * The modal field a command leaves on a track (pure; the agent tool shares
+ * it). A preset switch keeps the overrides; `reset` keeps the preset.
+ * `mallet` and `hardness` are one choice, so the one written last wins.
+ */
+export function nextModal(
+  current: TrackModal | undefined,
+  command: Extract<
+    ModalCommand,
+    { type: "modal-reset" | "modal-preset" | "modal-set" }
+  >,
+): TrackModal {
+  const base: Record<string, unknown> = { ...current };
+  if (command.type === "modal-reset")
+    return normalizeModal(current?.preset ? { preset: current.preset } : {})!;
+  if (command.type === "modal-preset") base.preset = command.preset;
+  else
+    for (const [key, value] of Object.entries(command.values)) {
+      if (value === null) delete base[key];
+      else {
+        base[key] = value;
+        if (key === "mallet" && !("hardness" in command.values))
+          delete base.hardness;
+        if (key === "hardness" && !("mallet" in command.values))
+          delete base.mallet;
+      }
+    }
+  return normalizeModal(base)!;
+}
+
+export function applyModalCommand(
+  score: TrackScore,
+  trackId: string,
+  command: ModalCommand,
+): ModalResult {
+  if (command.type === "modal-usage")
+    return { ok: false, message: `modal · ${command.message}` };
+  if (command.type === "modal-list")
+    return {
+      ok: true,
+      message: `modal presets · ${MODAL_PRESET_NAMES.join(" ")}`,
+    };
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return { ok: false, message: `no track · ${trackId}` };
+  if (command.type === "modal-show")
+    return {
+      ok: true,
+      message:
+        track.instrument === MODAL_INSTRUMENT && track.modal
+          ? `modal · ${describeModal(track.modal)}`
+          : `modal · ${trackId} plays ${track.instrument} · modal <preset> to switch (${MODAL_PRESET_NAMES.join(" ")})`,
+    };
+  if (track.sampler || track.instrument === "kit")
+    return {
+      ok: false,
+      message: `modal · ${trackId} is a ${track.sampler ? "sampler" : "drum"} track`,
+    };
+  const current =
+    track.instrument === MODAL_INSTRUMENT ? track.modal : undefined;
+  if (command.type === "modal-off") {
+    if (track.instrument !== MODAL_INSTRUMENT)
+      return { ok: true, message: "modal · already off" };
+    // Like `string off`: leave the engine for the legacy voice.
+    const next = updateTrack(score, trackId, {
+      instrument: MODAL_OFF_INSTRUMENT,
+      modal: null,
+    });
+    return {
+      ok: true,
+      message: `modal · off (${MODAL_OFF_INSTRUMENT}) · modal ${current?.preset ?? DEFAULT_MODAL_PRESET} turns it back on`,
+      next,
+      kind: "score.modal",
+      payload: { trackId, instrument: MODAL_OFF_INSTRUMENT, modal: null },
+    };
+  }
+  let modal: TrackModal;
+  let next: TrackScore;
+  try {
+    modal = nextModal(current, command);
+    next = updateTrack(score, trackId, {
+      instrument: MODAL_INSTRUMENT,
+      modal,
+    });
+  } catch (error) {
+    if (
+      error instanceof ScoreValidationError ||
+      error instanceof FxValidationError
+    )
+      return { ok: false, message: `modal · ${error.message}` };
+    throw error;
+  }
+  return {
+    ok: true,
+    message: `modal · ${describeModal(modal)}`,
+    next,
+    kind: "score.modal",
+    payload: { trackId, instrument: MODAL_INSTRUMENT, modal },
+  };
+}