@hraness/dawg 0.5.0 → 0.6.1

package/src/commands/rig.ts

@@ -0,0 +1,264 @@
+/**
+ * The guitar rig prompt commands (0.6):
+ *
+ *   rig                          show the focused track's rig
+ *   rig <preset>                 load a whole rig (RIG_PRESETS): clean crunch
+ *                                punk ragged lead metal fuzz octave funk wah
+ *                                bachata spring bassdrive reese jangle alt
+ *   rig reset | rig off          remove the stomp, head and cab
+ *   stomp|head|cab <type>        pick a pedal, amp or cabinet (`head crunch`)
+ *   stomp|head|cab <param> <v>…  set parameters (`head gain 7 gate -55`)
+ *   stomp|head|cab on|off|reset  as `fx <stage> …`
+ *
+ * Stage commands are `fx stomp|head|cab …` without the `fx`. `fx amp` (and
+ * `amp`) answer with a hint: `amp` stays Strudel's linear gain, the guitar
+ * amplifier is `head`. One command is one `updateTrack` revision.
+ */
+import {
+  FX_PRESETS,
+  FxValidationError,
+  RIG_PRESETS,
+  RIG_STAGES,
+  applyRigPreset,
+  effectSpec,
+  isRigReverb,
+  rigPresetOf,
+  rigReverb,
+  type FxValues,
+  type RigStage,
+  type TrackFx,
+  SHOEGAZE_EFFECTS,
+} from "../../core/fx.ts";
+import {
+  instrumentForWord,
+  resolveInstrumentWord,
+} from "../../core/instruments.ts";
+import {
+  ScoreValidationError,
+  updateTrack,
+  type TrackPatch,
+  type TrackScore,
+} from "../../core/score.ts";
+import {
+  applyFxCommand,
+  parseFxCommand,
+  type FxCommand,
+  type FxResult,
+} from "./fx.ts";
+
+export type RigCommand =
+  | { type: "rig-show" }
+  | { type: "rig-preset"; preset: string }
+  | { type: "rig-reset" }
+  | { type: "rig-stage"; stage: RigStage; fx: FxCommand }
+  /** A typed word that is close to a rig command: answer with a hint. */
+  | { type: "rig-hint"; message: string };
+
+export const RIG_PRESET_NAMES: readonly string[] = Object.freeze(
+  Object.keys(RIG_PRESETS),
+);
+
+const AMP_HINT =
+  "did you mean head (guitar amp)? · `head crunch`, `rig crunch` · amp stays Strudel linear gain (`fx gain`)";
+
+function isStage(word: string): word is RigStage {
+  return (RIG_STAGES as readonly string[]).includes(word);
+}
+
+/** `unknown rig crunh · did you mean crunch? · rigs clean crunch …` */
+function unknownRigMessage(name: string): string {
+  let best: { name: string; distance: number } | undefined;
+  for (const candidate of RIG_PRESET_NAMES) {
+    const distance = editDistance(name, candidate);
+    if (!best || distance < best.distance) best = { name: candidate, distance };
+  }
+  const near =
+    best && best.distance <= Math.max(2, Math.floor(name.length / 3))
+      ? ` · did you mean ${best.name}?`
+      : "";
+  return `unknown rig ${name}${near} · rigs ${RIG_PRESET_NAMES.join(" ")} reset`;
+}
+
+function editDistance(a: string, b: string): number {
+  let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    for (let j = 1; j <= b.length; j++)
+      next[j] = Math.min(
+        row[j]! + 1,
+        next[j - 1]! + 1,
+        row[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    row = next;
+  }
+  return row[b.length]!;
+}
+
+export function parseRigCommand(prompt: string): RigCommand | undefined {
+  if (prompt.length > 1_024) return undefined;
+  const words = prompt.trim().replace(/^\//, "").toLowerCase().split(/\s+/);
+  const head = words[0];
+  if (head === "amp" || (head === "fx" && words[1] === "amp"))
+    return { type: "rig-hint", message: AMP_HINT };
+  if (head === "rig") {
+    if (words.length === 1) return { type: "rig-show" };
+    const name = words.slice(1).join(" ");
+    if (name === "reset" || name === "off" || name === "none")
+      return { type: "rig-reset" };
+    if (Object.prototype.hasOwnProperty.call(RIG_PRESETS, name))
+      return { type: "rig-preset", preset: name };
+    return { type: "rig-hint", message: unknownRigMessage(name) };
+  }
+  if (!head || !isStage(head)) return undefined;
+  const stage = head;
+  const rest = words.slice(1);
+  if (rest.length === 0)
+    return { type: "rig-stage", stage, fx: { type: "fx-on", effect: stage } };
+  // `stomp fuzz`, `head crunch`, `cab 4x12`: the stage's type.
+  const types = effectSpec(stage).params.type;
+  if (
+    rest.length === 1 &&
+    types?.kind === "enum" &&
+    (types.values as readonly string[]).includes(rest[0]!)
+  )
+    return {
+      type: "rig-stage",
+      stage,
+      fx: { type: "fx-set", effect: stage, values: { type: rest[0]! } },
+    };
+  // `stomp muff`: a stage preset.
+  if (
+    rest.length === 1 &&
+    Object.prototype.hasOwnProperty.call(FX_PRESETS[stage] ?? {}, rest[0]!)
+  )
+    return {
+      type: "rig-stage",
+      stage,
+      fx: { type: "fx-preset", effect: stage, preset: rest[0]! },
+    };
+  const fx = parseFxCommand(`fx ${stage} ${rest.join(" ")}`);
+  return fx ? { type: "rig-stage", stage, fx } : undefined;
+}
+
+function describeRig(values: Readonly<Record<string, FxValues | undefined>>) {
+  const stages = RIG_STAGES.filter((stage) => values[stage])
+    .map((stage) => {
+      const v = values[stage]!;
+      const type = String(v.type);
+      const gain = v.gain === undefined ? "" : ` ${String(v.gain)}`;
+      return `${stage} ${type}${gain}`;
+    })
+    .join(" → ");
+  // 0.6.1 shoegaze stages follow the cab in the chain.
+  const gaze = SHOEGAZE_EFFECTS.filter((effect) => values[effect]);
+  return gaze.length ? `${stages} + ${gaze.join(" ")}` : stages;
+}
+
+export function applyRigCommand(
+  score: TrackScore,
+  trackId: string,
+  command: RigCommand,
+): FxResult {
+  if (command.type === "rig-hint")
+    return { ok: false, message: command.message };
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return { ok: false, message: `no track · ${trackId}` };
+  if (command.type === "rig-stage")
+    return applyFxCommand(score, trackId, command.fx);
+  if (command.type === "rig-show") {
+    const fx = track.fx ?? {};
+    if (!RIG_STAGES.some((stage) => fx[stage]))
+      return {
+        ok: true,
+        message: `rig · none · rigs ${RIG_PRESET_NAMES.join(" ")}`,
+      };
+    const name = rigPresetOf(track.fx);
+    return {
+      ok: true,
+      message: `rig${name ? ` ${name}` : ""} · ${describeRig(fx)}`,
+    };
+  }
+  const name = command.type === "rig-reset" ? "reset" : command.preset;
+  if (name === "reset" && !RIG_STAGES.some((stage) => track.fx?.[stage]))
+    return { ok: true, message: "rig · already off" };
+  let next: TrackScore;
+  try {
+    next = updateTrack(score, trackId, rigPatch(track, name));
+  } catch (error) {
+    if (
+      error instanceof ScoreValidationError ||
+      error instanceof FxValidationError
+    )
+      return { ok: false, message: `rig · ${error.message}` };
+    throw error;
+  }
+  const stored = next.tracks.find((candidate) => candidate.id === trackId)?.fx;
+  return {
+    ok: true,
+    message:
+      name === "reset"
+        ? "rig · off"
+        : `rig ${name} · ${describeRig(stored ?? {})}`,
+    next,
+    kind: "score.effect",
+    payload: { trackId, rig: name, fx: stored ?? null },
+  };
+}
+
+/**
+ * Track fields an instrument word sets beyond `instrument`: a rig alias
+ * (`jangle`, `punk`, `gtr-metal`…) also loads its rig over `fx`, keeping
+ * the track's other effects. Empty for every other word.
+ */
+export function rigWordPatch(
+  word: string,
+  fx: TrackFx | undefined,
+): Readonly<{ fx?: TrackFx | null; reverb?: TrackPatch["reverb"] }> {
+  const rig = resolveInstrumentWord(word)?.fx;
+  if (!rig || !Object.prototype.hasOwnProperty.call(RIG_PRESETS, rig))
+    return {};
+  return rigPatch({ fx }, rig);
+}
+
+/**
+ * The track patch for rig `name` (or `"reset"`): the stages and companion
+ * effects, plus `rig spring`'s short room. A reverb a previous rig set (and
+ * nobody changed since) is removed when the new rig has none.
+ */
+function rigPatch(
+  track: Readonly<{ fx?: TrackFx; reverb?: unknown }>,
+  name: string,
+): Readonly<{ fx: TrackFx | null; reverb?: TrackPatch["reverb"] }> {
+  const reverb = name === "reset" ? undefined : rigReverb(name);
+  return {
+    fx: applyRigPreset(track.fx, name) ?? null,
+    ...(reverb
+      ? { reverb: reverb as unknown as TrackPatch["reverb"] }
+      : isRigReverb(track.reverb)
+        ? { reverb: null }
+        : {}),
+  };
+}
+
+/**
+ * A new track's fields for instrument word `word`: a guitar alias gets its
+ * guitar voice and rig, any other word `{}` (callers pick the instrument).
+ */
+export function rigTrackFields(word: string): Readonly<{
+  instrument?: string;
+  string?: { preset: string };
+  fx?: TrackFx;
+  reverb?: TrackPatch["reverb"];
+}> {
+  const meaning = resolveInstrumentWord(word);
+  if (!meaning?.fx) return {};
+  const { fx, reverb } = rigWordPatch(word, undefined);
+  return {
+    instrument: meaning.instrument,
+    ...(meaning.field === "string" && meaning.preset
+      ? { string: { preset: meaning.preset } }
+      : {}),
+    ...(fx ? { fx } : {}),
+    ...(reverb ? { reverb } : {}),
+  };
+}

package/src/commands/sample.ts

@@ -38,7 +38,8 @@ export type SampleCommand =
     }>;
 
 /** A sample control value: a number, a switch, a unit, or null to unset. */
-export type SampleControlValue = number | string | boolean | null;
+export type SampleControlValue =
+  number | string | boolean | null | readonly number[];
 
 /**
  * Per-voice sample controls `/sample set` and `set_sample` change, by
@@ -59,6 +60,15 @@ export const SAMPLE_CONTROLS = Object.freeze({
   accelerate: "rate ramps by this × over the voice (−8..8)",
   squiz: "pitch-raise ratio per zero-crossing cycle (1..32)",
   cut: "choke group name: a new hit stops the previous one",
+  bpm: "the sample's own tempo: it follows the song's tempo map",
+  fitmode: "how a fitted sample changes time: repitch, beats or tones",
+  len: "the window lasts n beats of the song's tempo map",
+  shift: "pitch in semitones (−24..24), length unchanged",
+  formant: "formants in semitones with shift: 0 keeps the voice, off follows",
+  fadeTime: "release fade in seconds (0..2); alias fadeout",
+  fadeInTime: "attack fade in seconds (0..2); alias fadein",
+  vel: "velocity layer lo-hi (MIDI 0-127): plays only for those velocities",
+  rr: "round-robin group name: voices in a group take turns",
 });
 export type SampleControl = keyof typeof SAMPLE_CONTROLS;
 
@@ -67,6 +77,8 @@ const SAMPLE_ALIASES: Readonly<Record<string, string>> = {
   loope: "loopEnd",
   legato: "clip",
   choke: "cut",
+  fadeout: "fadeTime",
+  fadein: "fadeInTime",
 };
 
 function controlName(raw: string): SampleControl | undefined {
@@ -173,6 +185,18 @@ export function setSampleControls(
       continue;
     }
     if (name === "cut" && typeof value === "number") value = `cut${value}`;
+    if (name === "rr" && typeof value === "number") value = `rr${value}`;
+    if (name === "vel" && value !== null) {
+      const range = parseVelocityRange(value);
+      if (!range)
+        return {
+          ok: false,
+          message: "sample · vel needs lo-hi MIDI velocities, e.g. vel 0-63",
+        };
+      next.vel = range;
+      changed.push(`vel ${range[0]}-${range[1]}`);
+      continue;
+    }
     if (value === null) delete next[field];
     else next[field] = value;
     changed.push(`${raw} ${value === null ? "off" : String(value)}`);
@@ -200,10 +224,24 @@ export function setSampleControls(
   return {
     ok: true,
     next: updated,
-    message: `sample · ${trackId}/${voice} · ${changed.join(" · ")}`,
+    message: `sample · ${trackId}/${voice} · ${changed.join(" · ")}${layerHint(updated, trackId, voice)}`,
   };
 }
 
+/** `0-63`, `0..63`, `64` (one velocity) → [lo, hi]; else undefined. */
+export function parseVelocityRange(
+  value: SampleControlValue | readonly number[],
+): [number, number] | undefined {
+  if (Array.isArray(value))
+    return value.length === 2 && value.every((v) => typeof v === "number")
+      ? [value[0] as number, value[1] as number]
+      : undefined;
+  if (typeof value === "number") return [value, value];
+  if (typeof value !== "string") return undefined;
+  const match = value.trim().match(/^(\d{1,3})\s*(?:-|\.\.|,)\s*(\d{1,3})$/);
+  return match ? [Number(match[1]), Number(match[2])] : undefined;
+}
+
 function unquote(value: string): string {
   const quoted = value.match(/^(["'])(.*)\1$/);
   return quoted ? quoted[2]! : value;
@@ -369,6 +407,18 @@ export function freeVoiceName(
   }
 }
 
+/**
+ * One-shot velocity layers swap only within a round-robin group: a kit
+ * voice with `vel` and no `rr` keeps its own pad, so say how to join them.
+ */
+function layerHint(score: TrackScore, trackId: string, voice: string): string {
+  const sampler = score.tracks.find((item) => item.id === trackId)?.sampler;
+  const ref = sampler?.voices[voice];
+  if (sampler?.mode !== "oneshot" || !ref?.vel || ref.rr !== undefined)
+    return "";
+  return ` · one-shot layers share a pad only within an rr group: sample ${voice} rr <group> on each layer`;
+}
+
 export class SamplePlacementError extends Error {}
 
 /**

package/src/commands/shift.ts

@@ -0,0 +1,119 @@
+/**
+ * `shift <semitones> [formant keep|follow|<n>] [<voice>]` and
+ * `fade [in|out] <seconds> [<voice>]` (0.6.1): pitch a sampler voice
+ * without changing its length, and set its fade in and out. They act on
+ * the focused sampler track's voice (named, or its only one) through
+ * `setSampleControls`, so validation and printing stay the sampler's.
+ */
+import type { TrackScore } from "../../core/score.ts";
+import { fitVoice } from "./fit.ts";
+import {
+  setSampleControls,
+  type SampleControlValue,
+  type SetSampleResult,
+} from "./sample.ts";
+
+export type ShiftCommand =
+  | Readonly<{
+      kind: "shift";
+      /** Semitones; null clears shift and formant. */
+      semitones: number | null;
+      /** 0 keeps the formants, null follows the pitch, undefined leaves it. */
+      formant?: number | null;
+      voice?: string;
+    }>
+  | Readonly<{
+      kind: "fade";
+      /** `in` is fadeInTime, `out` fadeTime, `both` sets each. */
+      edge: "in" | "out" | "both";
+      seconds: number | null;
+      voice?: string;
+    }>;
+
+const VOICE = "([a-z][a-z0-9_]{0,31})";
+const NUMBER = "([+-]?\\d+(?:\\.\\d+)?|off|none)";
+
+/** Parse `shift ...` and `fade ...` (with or without the slash). */
+export function parseShiftCommand(command: string): ShiftCommand | undefined {
+  const text = command.trim();
+  const shift = text.match(
+    new RegExp(
+      `^/?shift\\s+${NUMBER}(?:\\s+formant\\s+(keep|follow|[+-]?\\d+(?:\\.\\d+)?))?(?:\\s+(?:voice\\s+)?${VOICE})?$`,
+      "i",
+    ),
+  );
+  if (shift) {
+    const raw = shift[1]!.toLowerCase();
+    const formant = shift[2]?.toLowerCase();
+    return {
+      kind: "shift",
+      semitones: raw === "off" || raw === "none" ? null : Number(raw),
+      ...(formant === undefined
+        ? {}
+        : {
+            formant:
+              formant === "keep"
+                ? 0
+                : formant === "follow"
+                  ? null
+                  : Number(formant),
+          }),
+      ...(shift[3] ? { voice: shift[3].toLowerCase() } : {}),
+    };
+  }
+  const fade = text.match(
+    new RegExp(
+      `^/?fade(?:\\s+(in|out))?\\s+${NUMBER}(?:\\s+(?:voice\\s+)?${VOICE})?$`,
+      "i",
+    ),
+  );
+  if (!fade) return undefined;
+  const raw = fade[2]!.toLowerCase();
+  return {
+    kind: "fade",
+    edge: (fade[1]?.toLowerCase() as "in" | "out" | undefined) ?? "both",
+    seconds: raw === "off" || raw === "none" ? null : Number(raw),
+    ...(fade[3] ? { voice: fade[3].toLowerCase() } : {}),
+  };
+}
+
+/** Apply a parsed `shift` or `fade` to the focused track's voice. */
+export function applyShiftCommand(
+  score: TrackScore,
+  trackId: string,
+  command: ShiftCommand,
+): SetSampleResult {
+  const target = fitVoice(score, trackId, command.voice);
+  if ("error" in target)
+    return {
+      ok: false,
+      message: target.error.replace(/^fit · /, `${command.kind} · `),
+    };
+  const values: Record<string, SampleControlValue> = {};
+  if (command.kind === "shift") {
+    // `shift off` clears the shift and its formant setting. `shift 0`
+    // clears the shift and a kept formant (0, a no-op without a shift) but
+    // keeps a formant move, so `shift 0 formant 3` is a formant-only move
+    // and stepping the shift through 0 keeps a stored formant.
+    if (command.semitones === null) {
+      values.shift = null;
+      values.formant = null;
+    } else {
+      values.shift = command.semitones === 0 ? null : command.semitones;
+      const formant =
+        command.formant !== undefined
+          ? command.formant
+          : score.tracks.find((track) => track.id === trackId)?.sampler?.voices[
+              target.voice
+            ]?.formant;
+      if (command.semitones === 0 && (formant === 0 || formant === null))
+        values.formant = null;
+      else if (command.formant !== undefined) values.formant = command.formant;
+    }
+  } else {
+    const seconds = command.seconds === 0 ? null : command.seconds;
+    if (command.edge !== "out") values.fadeInTime = seconds;
+    if (command.edge !== "in") values.fadeTime = seconds;
+  }
+  return setSampleControls(score, trackId, target.voice, values);
+}

package/src/commands/string.ts

@@ -0,0 +1,201 @@
+/**
+ * The `string` prompt command: the focused track's plucked-string engine
+ * (core/strings.ts, `Track.string`).
+ *
+ *   string                              list this track's preset and overrides
+ *   string presets                      the plucked presets
+ *   string <preset> | preset <name>     play a preset (instrument "string")
+ *   string <param> <value> [<param> <value>…]   override parameters
+ *   string <param> off                  back to the preset's value
+ *   string reset                        drop the overrides, keep the preset
+ *   string off                          back to the track's synth voice
+ *   bowed                               play the cello preset (bowed strings)
+ *   bowed <preset>                      a bowed preset (violin viola cello …)
+ *   bowed presets                       the bowed presets
+ *
+ * `string sitar`, `string buzz 0.8 sym 0.5`, `string ring 6`. Each command
+ * is one `updateTrack` revision and one undo step.
+ */
+import { FxValidationError } from "../../core/params.ts";
+import {
+  ScoreValidationError,
+  updateTrack,
+  type TrackScore,
+} from "../../core/score.ts";
+import {
+  BOWED_PRESET_NAMES,
+  DEFAULT_BOWED_PRESET,
+  DEFAULT_STRING_PRESET,
+  isStringTrack,
+  normalizeString,
+  STRING_INSTRUMENT,
+  STRING_PARAMS,
+  STRING_PRESET_NAMES,
+  STRING_PRESETS,
+  STRING_SIMPLE_PARAMS,
+  stringParamName,
+  stringPresetName,
+  stringPresetOf,
+  type TrackString,
+} from "../../core/strings.ts";
+import { parseParamValue } from "./fx.ts";
+
+export type StringCommand =
+  | { type: "string-list" }
+  | { type: "string-presets"; bowed?: boolean }
+  | { type: "string-reset" }
+  | { type: "string-off" }
+  | { type: "string-preset"; preset: string }
+  | {
+      type: "string-set";
+      /** `null` unsets a parameter (the preset's value again). */
+      values: Readonly<Record<string, number | string | null>>;
+    };
+
+export function parseStringCommand(prompt: string): StringCommand | undefined {
+  const words = prompt.trim().split(/\s+/);
+  if (words[0]?.toLowerCase() === "bowed") return parseBowed(words.slice(1));
+  if (words[0]?.toLowerCase() !== "string") return undefined;
+  if (words.length === 1) return { type: "string-list" };
+  if (prompt.length > 1_024) return undefined;
+  const rest = words.slice(1).map((word) => word.toLowerCase());
+  if (rest.length === 1) {
+    if (rest[0] === "reset") return { type: "string-reset" };
+    if (rest[0] === "off") return { type: "string-off" };
+    if (rest[0] === "presets" || rest[0] === "list")
+      return { type: "string-presets" };
+    const preset = stringPresetName(rest[0]!);
+    return preset ? { type: "string-preset", preset } : undefined;
+  }
+  if (rest[0] === "preset") {
+    const preset = rest.length === 2 ? stringPresetName(rest[1]!) : undefined;
+    return preset ? { type: "string-preset", preset } : undefined;
+  }
+  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 = stringParamName(rest[index]!);
+    if (!name) return undefined;
+    const word = rest[index + 1]!;
+    if (word === "off" || word === "unset") {
+      values[name] = null;
+      continue;
+    }
+    const value = parseParamValue(STRING_PARAMS[name]!, word);
+    if (value === undefined || typeof value === "boolean") return undefined;
+    values[name] = value;
+  }
+  return { type: "string-set", values };
+}
+
+/**
+ * `bowed` (0.6.1): the string engine's bowed family. `bowed` plays cello,
+ * `bowed <preset>` a bowed preset, `bowed presets` lists them, and
+ * `bowed <param> <value>…` is `string <param> <value>…`.
+ */
+function parseBowed(words: string[]): StringCommand | undefined {
+  if (words.length === 0)
+    return { type: "string-preset", preset: DEFAULT_BOWED_PRESET };
+  const rest = words.map((word) => word.toLowerCase());
+  if (rest.length === 1 && (rest[0] === "presets" || rest[0] === "list"))
+    return { type: "string-presets", bowed: true };
+  if (rest.length === 1) {
+    const preset = stringPresetName(rest[0]!);
+    return preset && BOWED_PRESET_NAMES.includes(preset)
+      ? { type: "string-preset", preset }
+      : undefined;
+  }
+  return parseStringCommand(`string ${rest.join(" ")}`);
+}
+
+/** `sitar · buzz 0.8 · sym 0.5`, or `nylon` for a bare preset. */
+export function describeString(settings: TrackString | undefined): string {
+  const parts = [stringPresetOf(settings)];
+  for (const [key, value] of Object.entries(settings ?? {}))
+    if (key !== "preset" && value !== undefined) parts.push(`${key} ${value}`);
+  return parts.join(" · ");
+}
+
+export type StringResult = Readonly<{
+  ok: boolean;
+  message: string;
+  next?: TrackScore;
+  kind?: string;
+  payload?: Record<string, unknown>;
+}>;
+
+export function applyStringCommand(
+  score: TrackScore,
+  trackId: string,
+  command: StringCommand,
+): StringResult {
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return { ok: false, message: `no track · ${trackId}` };
+  if (command.type === "string-presets")
+    return {
+      ok: true,
+      message: `${command.bowed ? "bowed" : "string"} presets · ${(command.bowed ? BOWED_PRESET_NAMES : STRING_PRESET_NAMES).map((name) => `${name} (${STRING_PRESETS[name]!.doc})`).join(" · ")}`,
+    };
+  if (track.sampler || track.kit)
+    return {
+      ok: false,
+      message: `string · ${trackId} is a ${track.sampler ? "sampler" : "drum"} track; the string engine plays pitched notes`,
+    };
+  const active = isStringTrack(track);
+  if (command.type === "string-list")
+    return {
+      ok: true,
+      message: active
+        ? `string · ${describeString(track.string)} · basics ${STRING_SIMPLE_PARAMS.join(" ")}`
+        : `string · off (${track.instrument}) · string ${DEFAULT_STRING_PRESET} turns it on · string presets`,
+    };
+  let instrument = track.instrument;
+  let string: Record<string, unknown> | null;
+  if (command.type === "string-off") {
+    if (!active) return { ok: true, message: "string · already off" };
+    instrument = "pluck";
+    string = null;
+  } else if (command.type === "string-reset") {
+    if (!active) return { ok: true, message: "string · already off" };
+    string = { preset: stringPresetOf(track.string) };
+  } else if (command.type === "string-preset") {
+    instrument = STRING_INSTRUMENT;
+    string = { preset: command.preset };
+  } else {
+    instrument = STRING_INSTRUMENT;
+    string = active ? { ...track.string } : { preset: DEFAULT_STRING_PRESET };
+    for (const [key, value] of Object.entries(command.values)) {
+      if (value === null) delete string[key];
+      else string[key] = value;
+    }
+  }
+  let next: TrackScore;
+  try {
+    next = updateTrack(score, trackId, {
+      instrument,
+      string: string === null ? null : (normalizeString(string) ?? null),
+    });
+  } catch (error) {
+    if (
+      error instanceof ScoreValidationError ||
+      error instanceof FxValidationError
+    )
+      return { ok: false, message: `string · ${error.message}` };
+    throw error;
+  }
+  const stored = next.tracks.find((candidate) => candidate.id === trackId);
+  return {
+    ok: true,
+    message:
+      command.type === "string-off"
+        ? `string · off · ${instrument}`
+        : `string · ${describeString(stored?.string)}`,
+    next,
+    kind: "score.string",
+    payload: {
+      trackId,
+      instrument: stored?.instrument ?? instrument,
+      string: stored?.string ?? null,
+    },
+  };
+}