@hraness/dawg 0.2.0 → 0.4.0

package/src/commands/synth.ts

@@ -0,0 +1,229 @@
+/**
+ * The `synth` prompt command: the focused track's synth voice parameters
+ * (core/synth.ts), named as in Strudel.
+ *
+ *   synth                               list the parameters this track sets
+ *   synth preset <name>                 load a preset (instrument + params)
+ *   synth <param> <value> [<param> <value>…]   set (Strudel aliases accepted)
+ *   synth <param> off                   unset one parameter (back to default)
+ *   synth partials 1 0.5 0.33           additive harmonics (also `phases`)
+ *   synth reset                         unset every parameter
+ *   synth zzfx 1,.05,220,,,.1,2         a raw ZzFX array (z_* sound + params)
+ *
+ * `synth lpf 800 lpenv 3 lpdecay 0.2`, `synth fm 4 fmh 1.5`, `synth adsr
+ * 0.01 0.2 0.5 0.3` (Strudel's `adsr` shorthand). 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 {
+  SYNTH_PARAMS,
+  SYNTH_PRESETS,
+  SYNTH_SIMPLE,
+  isSynthList,
+  isSynthPreset,
+  normalizeSynth,
+  synthParamName,
+  ZZFX_ARRAY_LAYOUT,
+  zzfxArraySynth,
+  type TrackSynth,
+} from "../../core/synth.ts";
+import { parseParamValue } from "./fx.ts";
+
+export type SynthCommand =
+  | { type: "synth-list" }
+  | { type: "synth-reset" }
+  | { type: "synth-preset"; preset: string }
+  /** A raw ZzFX parameter array (Strudel `zzfx([...])`); empty slots null. */
+  | { type: "synth-zzfx"; values: readonly (number | null)[] }
+  | {
+      type: "synth-set";
+      /** `null` unsets a parameter. */
+      values: Readonly<
+        Record<string, number | string | boolean | readonly number[] | null>
+      >;
+    };
+
+const ADSR = ["attack", "decay", "sustain", "release"] as const;
+
+export function parseSynthCommand(prompt: string): SynthCommand | undefined {
+  const words = prompt.trim().split(/\s+/);
+  if (words[0]?.toLowerCase() !== "synth") return undefined;
+  if (words.length === 1) return { type: "synth-list" };
+  if (prompt.length > 1_024) return undefined;
+  const rest = words.slice(1).map((word) => word.toLowerCase());
+  if (rest.length === 1 && (rest[0] === "reset" || rest[0] === "off"))
+    return { type: "synth-reset" };
+  if (rest[0] === "preset")
+    return rest.length === 2 && isSynthPreset(rest[1]!)
+      ? { type: "synth-preset", preset: rest[1]! }
+      : undefined;
+  const list = synthParamName(rest[0]!);
+  if (list && isSynthList(list)) {
+    if (rest.length === 2 && rest[1] === "off")
+      return { type: "synth-set", values: { [list]: null } };
+    const numbers = rest.slice(1).map(Number);
+    if (numbers.length === 0 || numbers.some((n) => !Number.isFinite(n)))
+      return undefined;
+    return { type: "synth-set", values: { [list]: numbers } };
+  }
+  if (rest[0] === "zzfx") return zzfxCommand(words.slice(2).join(" "));
+  if (rest[0] === "adsr") {
+    // Strudel's `adsr("a:d:s:r")`, as four words or one colon string.
+    const parts = rest.length === 2 ? rest[1]!.split(":") : rest.slice(1);
+    if (parts.length !== 4) return undefined;
+    const values: Record<string, number> = {};
+    for (const [index, name] of ADSR.entries()) {
+      const value = parseParamValue(SYNTH_PARAMS[name]!, parts[index]!);
+      if (typeof value !== "number") return undefined;
+      values[name] = value;
+    }
+    return { type: "synth-set", values };
+  }
+  if (rest.length % 2 !== 0) return undefined;
+  const values: Record<string, number | string | boolean | null> = {};
+  for (let index = 0; index < rest.length; index += 2) {
+    const name = synthParamName(rest[index]!);
+    if (!name || isSynthList(name)) return undefined;
+    const word = rest[index + 1]!;
+    if (word === "off" || word === "unset") {
+      values[name] = null;
+      continue;
+    }
+    const value = parseParamValue(SYNTH_PARAMS[name]!, word);
+    if (value === undefined) return undefined;
+    values[name] = value;
+  }
+  return { type: "synth-set", values };
+}
+
+/**
+ * `synth zzfx 1,.05,220,,,.1` or the pasted `zzfx(...[,,129,.01])` form:
+ * commas keep empty slots; without commas, spaces separate the values.
+ */
+function zzfxCommand(text: string): SynthCommand | undefined {
+  const body = text
+    .trim()
+    .replace(/^zzfx\s*\(/i, "")
+    .replace(/\)\s*;?$/, "")
+    .replace(/^\.\.\./, "")
+    .replace(/^\[/, "")
+    .replace(/\]$/, "")
+    .trim();
+  if (body.length === 0) return undefined;
+  const parts = body.includes(",") ? body.split(",") : body.split(/\s+/);
+  if (parts.length > ZZFX_ARRAY_LAYOUT.length) return undefined;
+  const values: (number | null)[] = [];
+  for (const part of parts) {
+    const word = part.trim();
+    if (word === "") {
+      values.push(null);
+      continue;
+    }
+    const value = Number(
+      word.startsWith(".") ? `0${word}` : word.replace(/^-\./, "-0."),
+    );
+    if (!Number.isFinite(value)) return undefined;
+    values.push(value);
+  }
+  return { type: "synth-zzfx", values };
+}
+
+/** `attack 0.01 · lpf 800 …` in spec order, or `defaults`. */
+export function describeSynth(synth: TrackSynth | undefined): string {
+  if (!synth) return "defaults";
+  return Object.entries(synth)
+    .map(([key, value]) =>
+      Array.isArray(value)
+        ? `${key} [${value.join(" ")}]`
+        : `${key} ${String(value)}`,
+    )
+    .join(" · ");
+}
+
+export type SynthResult = Readonly<{
+  ok: boolean;
+  message: string;
+  next?: TrackScore;
+  kind?: string;
+  payload?: Record<string, unknown>;
+}>;
+
+export function applySynthCommand(
+  score: TrackScore,
+  trackId: string,
+  command: SynthCommand,
+): SynthResult {
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return { ok: false, message: `no track · ${trackId}` };
+  if (track.sampler)
+    return {
+      ok: false,
+      message: `synth · ${trackId} is a sampler track; synth parameters shape synth voices`,
+    };
+  if (command.type === "synth-list")
+    return {
+      ok: true,
+      message: `synth · ${track.instrument} · ${describeSynth(track.synth)} · basics ${SYNTH_SIMPLE.join(" ")}`,
+    };
+  let instrument = track.instrument;
+  let synth: Record<string, unknown> | null;
+  if (command.type === "synth-reset") {
+    if (!track.synth) return { ok: true, message: "synth · already defaults" };
+    synth = null;
+  } else if (command.type === "synth-zzfx") {
+    try {
+      const sound = zzfxArraySynth(command.values);
+      instrument = sound.instrument;
+      synth = { ...sound.synth };
+    } catch (error) {
+      if (error instanceof FxValidationError)
+        return { ok: false, message: `synth · ${error.message}` };
+      throw error;
+    }
+  } else if (command.type === "synth-preset") {
+    const preset = SYNTH_PRESETS[command.preset]!;
+    instrument = preset.instrument;
+    synth = { ...preset.synth };
+  } else {
+    synth = { ...track.synth };
+    for (const [key, value] of Object.entries(command.values)) {
+      if (value === null) delete synth[key];
+      else synth[key] = value;
+    }
+  }
+  let next: TrackScore;
+  try {
+    const normalized = normalizeSynth(synth);
+    next = updateTrack(score, trackId, {
+      instrument,
+      synth: normalized ?? null,
+    });
+  } catch (error) {
+    if (
+      error instanceof ScoreValidationError ||
+      error instanceof FxValidationError
+    )
+      return { ok: false, message: `synth · ${error.message}` };
+    throw error;
+  }
+  const stored = next.tracks.find((candidate) => candidate.id === trackId);
+  return {
+    ok: true,
+    message:
+      command.type === "synth-preset"
+        ? `synth · preset ${command.preset} · ${stored?.instrument} · ${describeSynth(stored?.synth)}`
+        : `synth · ${describeSynth(stored?.synth)}`,
+    next,
+    kind: "score.synth",
+    payload: {
+      trackId,
+      instrument: stored?.instrument ?? instrument,
+      synth: stored?.synth ?? null,
+    },
+  };
+}

package/src/commands/wavetable.ts

@@ -0,0 +1,370 @@
+/**
+ * Wavetable commands (prompt grammar, menu and agent share these):
+ *
+ *   wt                      show the focused track's table and parameters
+ *   wt list                 built-in tables and the uzu-wavetables sets
+ *   wt <table>              play a table: basic, pwm, formant, harmonics,
+ *                           wt_digital:2 (Strudel's uzu-wavetables), any
+ *                           pack:<pack>/<sound>[:<n>], or a project WAV
+ *                           (vox.wav, wavetables/vox.wav, tracks/x/…/vox.wav;
+ *                           the agent's make_wavetable writes these)
+ *   wt <0..1>               position
+ *   wtenv|wtattack|wtdecay|wtsustain|wtrelease|wtrate|wtdepth|warp|wtphaserand <n>
+ *   warpmode <none|asym|bendp|bendm|bendmp|sync|quant>
+ *
+ * Any of these turns the focused track into a wavetable track. Parsing is
+ * pure; picking a pack table pins it (sha256 + url) through the PackStore.
+ */
+import {
+  BUILTIN_TABLE_PREFIX,
+  WARP_MODES,
+  WAVETABLE_INSTRUMENT,
+  WAVETABLE_PARAMS,
+  SCORE_LIMITS,
+  isLocalTableSrc,
+  isWavetableInstrument,
+  normalizeWavetable,
+  wavetableOf,
+  type ScoreOperation,
+  type TrackScore,
+  type TrackWavetable,
+  type WarpMode,
+  type WavetableParam,
+} from "../../core/score.ts";
+import { createHash } from "node:crypto";
+import { readdirSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { trackDirectories } from "../../core/sdk/print.ts";
+import { resolveReadPath } from "../agent/workspace.ts";
+import { PackError, type PackStore } from "../audio/packs.ts";
+import {
+  BUILTIN_TABLES,
+  BUILTIN_TABLE_NAMES,
+  wavetableFromWav,
+} from "../audio/wavetable.ts";
+
+/** The pack Strudel's `wt_` sounds come from. */
+export const WAVETABLE_PACK = "uzu-wavetables";
+
+/**
+ * Table names in uzu-wavetables' strudel.json (read 2026-10), for the menu,
+ * which cannot wait on a fetch. `wt list` reads the live manifest.
+ */
+export const UZU_WAVETABLES: Readonly<Record<string, readonly string[]>> =
+  Object.freeze({
+    wt_digital: ["bad_day", "basique", "crickets", "curses", "echoes"],
+    wt_vgame: Array.from({ length: 11 }, (_, i) => `vgame${10 + i}`),
+  });
+
+export type WavetableCommand =
+  | Readonly<{ kind: "show" }>
+  | Readonly<{ kind: "list" }>
+  | Readonly<{ kind: "table"; table: string }>
+  | Readonly<{ kind: "param"; param: WavetableParam; value: number }>
+  | Readonly<{ kind: "warpmode"; mode: WarpMode }>
+  | Readonly<{ kind: "usage"; message: string }>;
+
+const PARAM_WORDS = Object.keys(WAVETABLE_PARAMS).filter(
+  (name) => name !== "wt",
+) as WavetableParam[];
+const NUMBER = /^-?(?:\d+(?:\.\d+)?|\.\d+)$/;
+
+export function parseWavetableCommand(
+  command: string,
+): WavetableCommand | undefined {
+  const parsed = parseWords(command.trim().replace(/^\//, ""));
+  // Without a slash, only well-formed commands are ours; anything else
+  // ("warp the bass up") is a prompt for the agent.
+  if (parsed?.kind === "usage" && !command.trim().startsWith("/"))
+    return undefined;
+  return parsed;
+}
+
+function parseWords(text: string): WavetableCommand | undefined {
+  const words = text.split(/\s+/);
+  const head = words[0]!.toLowerCase();
+  if (head === "wavetable" || head === "wt") {
+    if (words.length === 1) return { kind: "show" };
+    if (words.length !== 2)
+      return { kind: "usage", message: "wt <table> | wt <0..1> | wt list" };
+    const arg = words[1]!;
+    if (/^(list|ls)$/i.test(arg)) return { kind: "list" };
+    if (NUMBER.test(arg)) {
+      const value = Number(arg);
+      if (value < 0 || value > 1)
+        return { kind: "usage", message: "wt position is 0..1" };
+      return { kind: "param", param: "wt", value };
+    }
+    return { kind: "table", table: arg };
+  }
+  if (head === "warpmode") {
+    const mode = words[1]?.toLowerCase();
+    if (words.length !== 2 || !WARP_MODES.includes(mode as WarpMode))
+      return {
+        kind: "usage",
+        message: `warpmode ${WARP_MODES.join("|")}`,
+      };
+    return { kind: "warpmode", mode: mode as WarpMode };
+  }
+  if ((PARAM_WORDS as string[]).includes(head)) {
+    const param = head as WavetableParam;
+    const [min, max] = WAVETABLE_PARAMS[param];
+    if (words.length !== 2 || !NUMBER.test(words[1]!))
+      return { kind: "usage", message: `${param} <${min}..${max}>` };
+    const value = Number(words[1]);
+    if (value < min || value > max)
+      return { kind: "usage", message: `${param} is ${min}..${max}` };
+    return { kind: "param", param, value };
+  }
+  return undefined;
+}
+
+/**
+ * `basic` → builtin, `wt_digital:2`/`wt_digital` → the uzu pack, `x/y[:n]`
+ * or `pack:x/y[:n]` → that pack sound. Undefined when malformed.
+ */
+export function wavetableSource(name: string): string | undefined {
+  const value = name.trim();
+  const lower = value.toLowerCase();
+  if (lower.startsWith(BUILTIN_TABLE_PREFIX))
+    return BUILTIN_TABLES[lower.slice(BUILTIN_TABLE_PREFIX.length)]
+      ? lower
+      : undefined;
+  if (BUILTIN_TABLES[lower]) return `${BUILTIN_TABLE_PREFIX}${lower}`;
+  if (/^wt_[a-z0-9_]+(?::[0-9]+)?$/i.test(value))
+    return `pack:${WAVETABLE_PACK}/${value}`;
+  if (
+    /^(?:pack:)?[a-z0-9._-]+\/[A-Za-z0-9._-]+(?::[A-Za-z0-9._-]+)?$/.test(value)
+  )
+    return value.startsWith("pack:") ? value : `pack:${value}`;
+  return undefined;
+}
+
+/** One operation that sets the track's wavetable (and makes it a wavetable track). */
+export function wavetableOperation(
+  score: TrackScore,
+  trackId: string,
+  next: TrackWavetable,
+): ScoreOperation {
+  const wavetable = normalizeWavetable(next)!;
+  if (!score.tracks.some((track) => track.id === trackId))
+    return {
+      type: "addTrack",
+      track: {
+        id: trackId,
+        name: trackId,
+        instrument: WAVETABLE_INSTRUMENT,
+        wavetable,
+      },
+    };
+  return {
+    type: "updateTrack",
+    trackId,
+    patch: { instrument: WAVETABLE_INSTRUMENT, wavetable },
+  };
+}
+
+function current(score: TrackScore, trackId: string): TrackWavetable {
+  const track = score.tracks.find((item) => item.id === trackId);
+  return track ? wavetableOf(track) : wavetableOf({} as never);
+}
+
+/** Pure parameter edit; the receipt line and the operation. */
+export function wavetableParamEdit(
+  score: TrackScore,
+  trackId: string,
+  command: Extract<WavetableCommand, { kind: "param" | "warpmode" }>,
+): { operation: ScoreOperation; summary: string } {
+  const base = current(score, trackId);
+  const next: Record<string, unknown> = { ...base };
+  let summary: string;
+  if (command.kind === "warpmode") {
+    next.warpmode = command.mode;
+    summary = `warpmode · ${command.mode}`;
+  } else {
+    next[command.param] = command.value;
+    summary = `${command.param} · ${formatNumber(command.value)}`;
+  }
+  return {
+    operation: wavetableOperation(score, trackId, next as TrackWavetable),
+    summary,
+  };
+}
+
+/** Directory project tables live in, under a track's directory. */
+export const LOCAL_TABLE_DIR = "wavetables";
+/** Most project tables `wt list` and the menu show. */
+const MAX_LISTED_TABLES = 200;
+
+/**
+ * Project wavetables: `tracks/<dir>/wavetables/*.wav`, sorted. Sync and
+ * bounded, so the menu can call it while it builds.
+ */
+export function listLocalWavetables(projectRoot: string | undefined): string[] {
+  if (!projectRoot) return [];
+  const out: string[] = [];
+  let dirs: string[];
+  try {
+    dirs = readdirSync(join(projectRoot, "tracks")).sort();
+  } catch {
+    return [];
+  }
+  for (const dir of dirs) {
+    if (dir.startsWith(".")) continue;
+    let files: string[];
+    try {
+      files = readdirSync(join(projectRoot, "tracks", dir, LOCAL_TABLE_DIR));
+    } catch {
+      continue;
+    }
+    for (const file of files.sort())
+      if (/\.wav$/i.test(file) && !file.startsWith("."))
+        out.push(`tracks/${dir}/${LOCAL_TABLE_DIR}/${file}`);
+    if (out.length >= MAX_LISTED_TABLES) break;
+  }
+  return out.slice(0, MAX_LISTED_TABLES);
+}
+
+/** True when a `wt` argument names a project WAV rather than a table name. */
+export function isLocalTableName(name: string): boolean {
+  return /\.wav$/i.test(name.trim()) && !name.trim().startsWith("pack:");
+}
+
+/**
+ * The project path for a local table argument: `tracks/…` as is, otherwise
+ * relative to the track's directory (`vox.wav` → its `wavetables/vox.wav`),
+ * falling back to the only project table with that file name.
+ */
+export function localTablePath(
+  score: TrackScore,
+  trackId: string,
+  name: string,
+  projectRoot?: string,
+): string {
+  const bare = name.trim().replace(/^\.\//, "");
+  if (bare.startsWith("tracks/")) return bare;
+  const dir = trackDirectories(score).get(trackId) ?? trackId;
+  const own = `tracks/${dir}/${bare.includes("/") ? bare : `${LOCAL_TABLE_DIR}/${bare}`}`;
+  if (bare.includes("/")) return own;
+  const all = listLocalWavetables(projectRoot);
+  if (all.includes(own)) return own;
+  const matches = all.filter((path) => path.endsWith(`/${bare}`));
+  return matches.length === 1 ? matches[0]! : own;
+}
+
+/** Resolves and pins a table name; pack tables are fetched once to pin them. */
+export async function pickWavetable(
+  store: PackStore,
+  score: TrackScore,
+  trackId: string,
+  name: string,
+  projectRoot?: string,
+): Promise<{ operation: ScoreOperation; summary: string }> {
+  if (isLocalTableName(name)) {
+    if (!projectRoot)
+      throw new PackError("project tables need an open project");
+    const src = localTablePath(score, trackId, name, projectRoot);
+    let sha256: string;
+    try {
+      const resolved = await resolveReadPath(
+        { root: projectRoot, trackSlug: "" },
+        src,
+        "wavetable",
+      );
+      const info = await stat(resolved.real);
+      if (!info.isFile()) throw new Error("not a file");
+      if (info.size > SCORE_LIMITS.maxSampleFileBytes)
+        throw new Error("over the 50 MiB file limit");
+      const bytes = new Uint8Array(await readFile(resolved.real));
+      wavetableFromWav(src, "check", bytes);
+      sha256 = createHash("sha256").update(bytes).digest("hex");
+    } catch (error) {
+      const why = error instanceof Error ? error.message : String(error);
+      throw new PackError(
+        `${src.slice(0, 80)} · ${why.slice(0, 120)} · wt list shows the project's tables`,
+      );
+    }
+    const base = current(score, trackId);
+    return {
+      operation: wavetableOperation(score, trackId, {
+        ...base,
+        table: { src, sha256 },
+      }),
+      summary: `wavetable · ${describeTable(src)}`,
+    };
+  }
+  const src = wavetableSource(name);
+  if (!src)
+    throw new PackError(
+      `${name.slice(0, 40)} is not a table · wt list shows ${BUILTIN_TABLE_NAMES.join(", ")} and the wt_ sets`,
+    );
+  const base = current(score, trackId);
+  const table = src.startsWith(BUILTIN_TABLE_PREFIX)
+    ? { src }
+    : await store.pin(src);
+  return {
+    operation: wavetableOperation(score, trackId, { ...base, table }),
+    summary: `wavetable · ${describeTable(table.src)}`,
+  };
+}
+
+export function describeTable(src: string): string {
+  if (src.startsWith(BUILTIN_TABLE_PREFIX)) {
+    const name = src.slice(BUILTIN_TABLE_PREFIX.length);
+    return `${name} (${BUILTIN_TABLES[name]?.title ?? "built-in"})`;
+  }
+  if (isLocalTableSrc(src)) return `${src.split("/").pop()} (project)`;
+  return src.replace(`pack:${WAVETABLE_PACK}/`, "");
+}
+
+/** `wt` reply: table and the parameters that differ from default. */
+export function describeWavetable(score: TrackScore, trackId: string): string {
+  const track = score.tracks.find((item) => item.id === trackId);
+  if (!track || !isWavetableInstrument(track.instrument))
+    return `${trackId} is not a wavetable track · wt basic makes it one`;
+  const settings = wavetableOf(track);
+  const params = (Object.keys(WAVETABLE_PARAMS) as WavetableParam[])
+    .filter((name) => settings[name] !== undefined)
+    .map((name) => `${name} ${formatNumber(settings[name]!)}`);
+  if (settings.warpmode) params.push(`warpmode ${settings.warpmode}`);
+  return `wavetable · ${describeTable(settings.table.src)}${params.length ? ` · ${params.join(" · ")}` : ""}`;
+}
+
+/** Lines for `wt list`: built-ins, then each uzu set with its table count. */
+export async function wavetableListLines(
+  store: PackStore | undefined,
+  projectRoot?: string,
+): Promise<string[]> {
+  const lines = ["built-in (offline):"];
+  for (const name of BUILTIN_TABLE_NAMES)
+    lines.push(`  ${name.padEnd(10)} ${BUILTIN_TABLES[name]!.title}`);
+  const local = listLocalWavetables(projectRoot);
+  lines.push("", "project (tracks/<slug>/wavetables/, made by the agent):");
+  if (local.length === 0)
+    lines.push(
+      "  none yet · ask the agent to make_wavetable from any audio file",
+    );
+  for (const path of local) lines.push(`  wt ${path}`);
+  lines.push("", `${WAVETABLE_PACK} (Strudel wt_ sounds, fetched on use):`);
+  try {
+    if (!store) throw new PackError("offline");
+    const manifest = await store.manifest(WAVETABLE_PACK);
+    for (const [sound, entry] of manifest.sounds) {
+      if (!sound.startsWith("wt_") || entry.kind !== "list") continue;
+      const count = entry.files.length;
+      lines.push(
+        `  ${sound.padEnd(12)} ${count} tables · wt ${sound}:0 … ${sound}:${count - 1}`,
+      );
+    }
+  } catch {
+    lines.push(
+      "  wt_digital, wt_vgame · wt wt_digital:0 (needs the network once)",
+    );
+  }
+  return lines;
+}
+
+function formatNumber(value: number): string {
+  return String(Math.round(value * 1000) / 1000);
+}