@hraness/dawg 0.5.0 → 0.6.0

package/src/commands/granular.ts

@@ -0,0 +1,427 @@
+/**
+ * The `grain` prompt command: the focused track's granular instrument
+ * (core/granular.ts, `Track.granular`).
+ *
+ *   grain                               this track's preset, source and overrides
+ *   grain presets                       the granular presets
+ *   grain <preset> | preset <name>      play a preset (instrument "granular")
+ *   grain on [voice V]                  grain this track's own sound
+ *   grain src synth:<name>[@note]       a built-in synth source
+ *   grain src voice <V>                 a sampler voice of this track as source
+ *   grain <param> <value> [...]         override parameters (`off` unsets)
+ *   grain reset                         drop the overrides, keep preset and source
+ *   grain off                           back to the track's previous voice
+ *
+ * On a synth track the source is that synth (`synth:<instrument>`), on a
+ * sampler the first (or named) voice, pinned like the sampler voice. Each
+ * command is one `updateTrack` revision and one undo step.
+ */
+import {
+  DEFAULT_GRANULAR_SOURCE,
+  GRANULAR_INSTRUMENT,
+  GRANULAR_PARAMS,
+  GRANULAR_PRESET_NAMES,
+  GRANULAR_PRESETS,
+  granularSourceLabel,
+  isGranularInstrument,
+  isGranularPreset,
+  normalizeGranular,
+  resolveGranular,
+  parseSynthSource,
+  synthSourceNames,
+  SYNTH_SOURCE_PREFIX,
+  type GranularPresetName,
+  type GranularSource,
+  type TrackGranular,
+} from "../../core/granular.ts";
+import { isDrumInstrument } from "../../core/drums.ts";
+import { FxValidationError } from "../../core/params.ts";
+import {
+  ScoreValidationError,
+  updateTrack,
+  type Track,
+  type TrackScore,
+} from "../../core/score.ts";
+import { pitchToMidi } from "../../core/pitch.ts";
+import { normalizeSynth, SYNTH_PRESETS } from "../../core/synth.ts";
+import { parseParamValue } from "./fx.ts";
+
+/** `grain 0.12s · overlap 6 · scan 0.25x …`; overrides marked `*`. */
+function basicsLine(settings: TrackGranular | undefined): string {
+  const resolved = resolveGranular(settings) as Record<string, unknown>;
+  return GRANULAR_SIMPLE_PARAMS.map((name) => {
+    const spec = GRANULAR_PARAMS[name]!;
+    const value = resolved[name];
+    const unit =
+      spec.kind === "number" && spec.unit
+        ? spec.unit
+        : name === "scan"
+          ? "x"
+          : "";
+    const shown =
+      typeof value === "number"
+        ? `${Number(value.toFixed(3))}${unit}`
+        : String(value);
+    const mark =
+      settings && Object.prototype.hasOwnProperty.call(settings, name)
+        ? "*"
+        : "";
+    return `${name} ${shown}${mark}`;
+  }).join(" · ");
+}
+
+/** The basics shown first in the menu and the `grain` listing. */
+export const GRANULAR_SIMPLE_PARAMS = Object.freeze([
+  "grain",
+  "overlap",
+  "scan",
+  "pos",
+  "spray",
+  "pitch",
+  "shimmer",
+  "spread",
+  "freeze",
+]);
+
+export type GranularCommand =
+  | { type: "grain-list" }
+  | { type: "grain-presets" }
+  | { type: "grain-reset" }
+  | { type: "grain-off" }
+  | { type: "grain-on"; voice?: string }
+  | { type: "grain-preset"; preset: GranularPresetName; voice?: string }
+  | { type: "grain-src"; synth?: string; voice?: string }
+  | {
+      type: "grain-set";
+      /** `null` unsets a parameter (the preset's value again). */
+      values: Readonly<Record<string, number | string | boolean | null>>;
+    };
+
+const VOICE_NAME = /^[a-z0-9._-]{1,64}$/;
+
+export function parseGranularCommand(
+  prompt: string,
+): GranularCommand | undefined {
+  const words = prompt.trim().split(/\s+/);
+  const head = words[0]?.toLowerCase();
+  if (head !== "grain" && head !== "granular") return undefined;
+  if (words.length === 1) return { type: "grain-list" };
+  if (prompt.length > 1_024) return undefined;
+  const rest = words.slice(1).map((word) => word.toLowerCase());
+  const voiceAt = (index: number): string | undefined | null => {
+    if (rest.length === index) return undefined;
+    if (
+      rest.length === index + 2 &&
+      rest[index] === "voice" &&
+      VOICE_NAME.test(rest[index + 1]!)
+    )
+      return rest[index + 1]!;
+    return null;
+  };
+  if (rest[0] === "reset" && rest.length === 1) return { type: "grain-reset" };
+  if (rest[0] === "off" && rest.length === 1) return { type: "grain-off" };
+  if ((rest[0] === "presets" || rest[0] === "list") && rest.length === 1)
+    return { type: "grain-presets" };
+  if (rest[0] === "on") {
+    const voice = voiceAt(1);
+    return voice === null ? undefined : { type: "grain-on", voice };
+  }
+  // `hold` is a preset and a parameter: `grain hold 4` sets the parameter.
+  const presetWord =
+    rest[0] === "preset" ||
+    (isGranularPreset(rest[0]!) &&
+      (rest.length === 1 ||
+        rest[1] === "voice" ||
+        !GRANULAR_PARAMS[rest[0]!] ||
+        rest.length % 2 !== 0));
+  if (presetWord) {
+    const at = rest[0] === "preset" ? 1 : 0;
+    const name = rest[at];
+    if (!name || !isGranularPreset(name)) return undefined;
+    const voice = voiceAt(at + 1);
+    return voice === null
+      ? undefined
+      : { type: "grain-preset", preset: name, voice };
+  }
+  if (rest[0] === "src" || rest[0] === "source") {
+    if (rest.length === 3 && rest[1] === "voice" && VOICE_NAME.test(rest[2]!))
+      return { type: "grain-src", voice: rest[2]! };
+    if (rest.length !== 2) return undefined;
+    const text = rest[1]!.startsWith(SYNTH_SOURCE_PREFIX)
+      ? rest[1]!
+      : `${SYNTH_SOURCE_PREFIX}${rest[1]!}`;
+    return parseSynthSource(text)
+      ? { type: "grain-src", synth: text }
+      : undefined;
+  }
+  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 = rest[index]!;
+    const spec = GRANULAR_PARAMS[name];
+    if (!spec) return undefined;
+    const word = rest[index + 1]!;
+    if ((word === "off" || word === "unset") && spec.kind !== "boolean") {
+      values[name] = null;
+      continue;
+    }
+    const value =
+      name === "root" && !/^\d/.test(word)
+        ? noteNumber(word)
+        : parseParamValue(spec, word);
+    if (value === undefined) return undefined;
+    values[name] = value;
+  }
+  return { type: "grain-set", values };
+}
+
+/** A note name (`c4`, `f#3`) as its MIDI number. */
+function noteNumber(word: string): number | undefined {
+  const midi = pitchToMidi(word);
+  return Number.isFinite(midi) ? midi : undefined;
+}
+
+/** `cloud · synth:pad · scan 0.1`, preset first, then source and overrides. */
+export function describeGranular(settings: TrackGranular | undefined): string {
+  const parts = [
+    settings?.preset ?? "default",
+    granularSourceLabel(settings?.src),
+  ];
+  for (const [key, value] of Object.entries(settings ?? {}))
+    if (
+      key !== "preset" &&
+      key !== "src" &&
+      key !== "from" &&
+      value !== undefined
+    )
+      parts.push(`${key} ${String(value)}`);
+  return parts.join(" · ");
+}
+
+/**
+ * The source a track's own sound gives: a sampler voice (the named one or
+ * the first), the track's synth when it is a known synth source, else the
+ * built-in pad.
+ */
+export function ownGranularSource(
+  track: Track,
+  voice?: string,
+): { src: GranularSource } | { error: string } {
+  if (track.sampler) {
+    const names = Object.keys(track.sampler.voices);
+    const name = voice ?? names[0];
+    const ref = name === undefined ? undefined : track.sampler.voices[name];
+    if (!ref)
+      return {
+        error: `no sampler voice ${voice ?? ""} on ${track.id} (${names.join(" ") || "none"})`,
+      };
+    return { src: ref };
+  }
+  if (voice !== undefined)
+    return { error: `${track.id} has no sampler voices` };
+  if (track.granular?.src !== undefined) return { src: track.granular.src };
+  // `synth preset pad` stores supersaw plus pad's params: grain the preset.
+  const preset = synthPresetOf(track);
+  if (preset) return { src: `${SYNTH_SOURCE_PREFIX}${preset}` };
+  // A sound plays with the track's own synth params (src/audio/granular.ts).
+  if (synthSourceNames().includes(track.instrument))
+    return { src: `${SYNTH_SOURCE_PREFIX}${track.instrument}` };
+  return { src: DEFAULT_GRANULAR_SOURCE };
+}
+
+/** The synth preset a track's instrument and synth params are, if any. */
+export function synthPresetOf(track: Track): string | undefined {
+  if (!track.synth) return undefined;
+  const own = JSON.stringify(track.synth);
+  for (const [name, preset] of Object.entries(SYNTH_PRESETS))
+    if (
+      preset.instrument === track.instrument &&
+      JSON.stringify(normalizeSynth({ ...preset.synth })) === own
+    )
+      return name;
+  return undefined;
+}
+
+export type GranularResult = Readonly<{
+  ok: boolean;
+  message: string;
+  next?: TrackScore;
+  kind?: string;
+  payload?: Record<string, unknown>;
+}>;
+
+/**
+ * The patch a granular change writes: instrument granular plus the
+ * validated settings, or `null` settings to turn it off.
+ */
+export function applyGranularCommand(
+  score: TrackScore,
+  trackId: string,
+  command: GranularCommand,
+): GranularResult {
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return { ok: false, message: `no track · ${trackId}` };
+  if (command.type === "grain-presets")
+    return {
+      ok: true,
+      message: `grain presets · ${GRANULAR_PRESET_NAMES.map((name) => `${name} (${GRANULAR_PRESETS[name].doc})`).join(" · ")}`,
+    };
+  if (track.kit || isDrumInstrument(track.instrument))
+    return {
+      ok: false,
+      message: `grain · ${trackId} is a drum track; granular plays pitched notes`,
+    };
+  const active = isGranularInstrument(track.instrument);
+  if (command.type === "grain-list")
+    return {
+      ok: true,
+      message: active
+        ? `grain · ${track.granular?.preset ?? "default"} · ${granularSourceLabel(track.granular?.src)} · ${basicsLine(track.granular)}`
+        : `grain · off (${track.instrument}) · grain cloud turns it on · grain presets`,
+    };
+  let instrument = track.instrument;
+  let granular: Record<string, unknown> | null;
+  let synthPatch: Record<string, unknown> | undefined;
+  const keepSrc = (): Record<string, unknown> | { error: string } => {
+    const own = ownGranularSource(track);
+    if ("error" in own) return own;
+    return own.src === DEFAULT_GRANULAR_SOURCE ? {} : { src: own.src };
+  };
+  if (command.type === "grain-off") {
+    if (!active) return { ok: true, message: "grain · already off" };
+    // A sampler keeps its voices; anything else returns to its synth
+    // source's voice (or sine), and the settings stay for `grain on`.
+    // The voice granular turned on from (`from`), else a wavetable, else
+    // the synth source's own instrument (a preset maps to its instrument
+    // and params), else sine.
+    const src = track.granular?.src;
+    const parsed = typeof src === "string" ? parseSynthSource(src) : undefined;
+    if (track.sampler) instrument = "sampler";
+    else if (track.granular?.from) instrument = track.granular.from;
+    else if (track.wavetable) instrument = "wavetable";
+    else if (parsed && SYNTH_PRESETS[parsed.name]) {
+      instrument = SYNTH_PRESETS[parsed.name]!.instrument;
+      if (!track.synth) synthPatch = { ...SYNTH_PRESETS[parsed.name]!.synth };
+    } else if (parsed) instrument = parsed.name;
+    else instrument = "sine";
+    granular = track.granular ? { ...track.granular } : null;
+  } else if (command.type === "grain-reset") {
+    if (!active) return { ok: true, message: "grain · already off" };
+    granular = {};
+    if (track.granular?.preset) granular.preset = track.granular.preset;
+    if (track.granular?.src !== undefined) granular.src = track.granular.src;
+  } else if (command.type === "grain-on" || command.type === "grain-preset") {
+    instrument = GRANULAR_INSTRUMENT;
+    const base: Record<string, unknown> =
+      active || (track.granular && command.voice === undefined)
+        ? { ...track.granular }
+        : {};
+    if (command.voice !== undefined || base.src === undefined) {
+      const own =
+        command.voice !== undefined
+          ? ownGranularSource(track, command.voice)
+          : ((): { src: GranularSource } | { error: string } => {
+              const kept = keepSrc();
+              if ("error" in kept) return kept as { error: string };
+              return {
+                src: (kept.src as GranularSource) ?? DEFAULT_GRANULAR_SOURCE,
+              };
+            })();
+      if ("error" in own) return { ok: false, message: `grain · ${own.error}` };
+      if (own.src === DEFAULT_GRANULAR_SOURCE) delete base.src;
+      else base.src = own.src;
+    }
+    if (command.type === "grain-preset") {
+      // A preset replaces the overrides; the source stays.
+      granular = { preset: command.preset };
+      if (base.src !== undefined) granular.src = base.src;
+    } else granular = base;
+  } else if (command.type === "grain-src") {
+    instrument = GRANULAR_INSTRUMENT;
+    granular = active || track.granular ? { ...track.granular } : {};
+    if (command.voice !== undefined) {
+      const own = ownGranularSource(track, command.voice);
+      if ("error" in own) return { ok: false, message: `grain · ${own.error}` };
+      granular.src = own.src;
+    } else if (command.synth === DEFAULT_GRANULAR_SOURCE) delete granular.src;
+    else granular.src = command.synth;
+  } else {
+    instrument = GRANULAR_INSTRUMENT;
+    granular = active && track.granular ? { ...track.granular } : {};
+    if (!active) {
+      const kept = keepSrc();
+      if ("error" in kept)
+        return { ok: false, message: `grain · ${kept.error}` };
+      Object.assign(granular, track.granular ?? {}, kept);
+    }
+    for (const [key, value] of Object.entries(command.values)) {
+      if (value === null) delete granular[key];
+      else granular[key] = value;
+    }
+  }
+  // Remember the voice to go back to when granular turns on.
+  if (granular !== null && command.type !== "grain-off") {
+    const from = active
+      ? track.granular?.from
+      : track.sampler || isGranularInstrument(track.instrument)
+        ? undefined
+        : track.instrument;
+    if (from) granular.from = from;
+    else delete granular.from;
+  }
+  let next: TrackScore;
+  try {
+    next = updateTrack(score, trackId, {
+      instrument,
+      granular: granular === null ? null : granularOrEmpty(granular),
+      ...(synthPatch ? { synth: synthPatch as never } : {}),
+    });
+  } catch (error) {
+    if (
+      error instanceof ScoreValidationError ||
+      error instanceof FxValidationError
+    )
+      return { ok: false, message: `grain · ${error.message}` };
+    throw error;
+  }
+  const stored = next.tracks.find((candidate) => candidate.id === trackId);
+  return {
+    ok: true,
+    message:
+      command.type === "grain-off"
+        ? `grain · off · ${instrument}`
+        : `grain · ${describeGranular(stored?.granular)}`,
+    next,
+    kind: "score.granular",
+    payload: {
+      trackId,
+      instrument: stored?.instrument ?? instrument,
+      granular: stored?.granular ?? null,
+    },
+  };
+}
+
+/** Validated settings; the score's normaliser re-checks the SampleRef. */
+function granularOrEmpty(value: Record<string, unknown>): TrackGranular {
+  return normalizeGranular(value, (ref) => ref as never) ?? Object.freeze({});
+}
+
+/** Track names that create a granular track: `cloud`, `hold-2`, … */
+export function granularTrackPreset(
+  trackId: string,
+): GranularPresetName | undefined {
+  const match = /^([a-z]+)(?:-\d{1,3})?$/.exec(trackId);
+  return match && isGranularPreset(match[1]!) ? match[1] : undefined;
+}
+
+/**
+ * The local answer for `grain src <something else>` (`grain src bus:guitars`),
+ * so a source dawg cannot read yet never goes to the agent.
+ */
+export function grainSrcHint(prompt: string): string | undefined {
+  const words = prompt.trim().toLowerCase().split(/\s+/);
+  if (words[0] !== "grain" || (words[1] !== "src" && words[1] !== "source"))
+    return undefined;
+  if (parseGranularCommand(prompt)) return undefined;
+  return "grain src synth:<preset>[@note] | voice <name> · a bus or another track is not a source yet: render it and load the file as a sampler voice";
+}

package/src/commands/help.ts

@@ -53,6 +53,12 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         command: "wtenv|wtattack|wtdecay|wtrate|wtdepth|warp <n>",
         summary: "scan the table · warpmode bendp",
       },
+      {
+        command:
+          "grain <preset> | <param> <value> | on [voice V] | src synth:<name>|voice V | reset | off",
+        summary:
+          "granular cloud · grain cloud · grain scan 0.2 · track swarm-2 · grain presets",
+      },
       {
         command: "fx <effect> <param> <value> | on | off | preset <name>",
         summary: "effects · fx delay mix 0.3 · fx reverb on · fx lists them",
@@ -61,6 +67,39 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         command: "synth <param> <value> | preset <name>",
         summary: "synth voice · synth lpf 1200 · synth lists every param",
       },
+      {
+        command: "string <preset> | <param> <value> | presets | reset | off",
+        summary:
+          "plucked strings · string sitar · string buzz 0.8 · string ring 6",
+      },
+      {
+        command: "rig <preset> | reset",
+        summary:
+          "guitar rig · rig crunch · rig metal · rig funk · rig lists them",
+      },
+      {
+        command: "track jangle|punk|funk|ragged|gtr-lead|gtr-metal|bachata",
+        summary: "new guitar track with that rig",
+      },
+      {
+        command: "stomp|head|cab <type> | <param> <value>",
+        summary:
+          "pedal, amp, cabinet · stomp rat · head gain 7 gate -55 · cab 4x12",
+      },
+      {
+        command: "piano [<preset>] | grand | upright | felt | honkytonk",
+        summary: "modelled piano · piano ballad · piano lofi · piano prepared",
+      },
+      {
+        command: "keys <param> <value> | preset <name> | reset",
+        summary: "piano params · keys hardness 0.3 decay 1.5 · keys lists them",
+      },
+      {
+        command:
+          "modal <preset> | <param> <value> | mallet <name> | reset | off",
+        summary:
+          "mallets and bells · modal vibes · modal hardness 0.8 · modal presets",
+      },
       {
         command: "art <articulation>|off [target]",
         summary:
@@ -224,6 +263,19 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         command: "/sample [<path> [as <voice>]]",
         summary: "add a sample voice · list voices",
       },
+      {
+        command: "/bpm <n> [<voice>]",
+        summary:
+          "the sample's own tempo (slash needed: bare bpm is song tempo)",
+      },
+      {
+        command: "/fitmode [repitch|beats|tones|auto] [<voice>]",
+        summary: "how it fits · alone suggests one from the sound",
+      },
+      {
+        command: "/len <beats> [<voice>]",
+        summary: "the sample lasts n beats of the song",
+      },
     ],
   },
   {
@@ -366,7 +418,7 @@ export const HELP_GUIDE: readonly HelpSection[] = [
     entries: [
       {
         command: "ctrl-k › Sound",
-        summary: "instrument, envelope, filter, wavetable",
+        summary: "instrument, strings, envelope, filter, wavetable",
       },
       { command: "ctrl-k › Effects", summary: "delay, reverb, distortion …" },
       {
@@ -561,7 +613,7 @@ export const USAGE: Readonly<Record<string, string>> = {
   grid: "/grid 1/4|1/8|1/8T|1/16|1/16T|1/32",
   tempo:
     "tempo takes 20…300 · tempo 120 · tempo 90 at bar 9 [ramp|exp] · tempo remove bar 9 · tempo clear · tempo map",
-  bpm: "tempo takes 20…300 · tempo 120",
+  bpm: "tempo takes 20…300 · tempo 120 · a sample's own tempo: /bpm 174 [<voice>] · /bpm off",
   rit: "rit [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · rit 4 bars to 80",
   ritardando:
     "rit [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · rit 4 bars to 80",
@@ -583,12 +635,16 @@ export const USAGE: Readonly<Record<string, string>> = {
   bars: "bars takes 1…256 · bars 8",
   extend: "extend <count> bars · extend 4 bars",
   instrument:
-    "instrument <name> · sine piano pluck bass saw square triangle wavetable kit · synth: sawtooth supersaw pulse white pink z_square…",
+    "instrument <name> · sine piano pluck bass saw square triangle wavetable kit · pianos: grand upright felt honkytonk prepared · synth: sawtooth supersaw pulse white pink z_square…",
   volume: "volume takes 0…1 · volume 0.8",
   vol: "volume takes 0…1 · volume 0.8",
   pan: "pan takes -1…1 · pan -0.5",
   wt: "wt <table> | wt <0..1> | wt list · wt basic · wt wt_digital:2",
   wavetable: "wt <table> | wt <0..1> | wt list · wt basic · wt wt_digital:2",
+  grain:
+    "grain <preset> | <param> <value> | on [voice V] | src synth:<name>|voice V | reset | off | presets · grain cloud · grain pitch 12",
+  granular:
+    "grain <preset> | <param> <value> | on [voice V] | src synth:<name>|voice V | reset | off | presets · grain cloud",
   warpmode: "warpmode none|asym|bendp|bendm|bendmp|sync|quant",
   filter: "filter <hz> [res] · filter 800 0.3 · filter off",
   delay: "delay <beats> [fb] [mix] · delay 0.75 0.4 0.3 · delay off",
@@ -611,6 +667,9 @@ export const USAGE: Readonly<Record<string, string>> = {
   sample:
     "/sample <path> [as <voice>] · /sample set <voice> <control> <value>… · /sample set brk fit on clip 1",
   samples: "/sample · lists the focused track's voices",
+  fitmode:
+    "/fitmode [repitch|beats|tones|auto|off] [<voice>] · /fitmode beats · /fitmode auto brk",
+  len: "/len <beats> [<voice>] · /len 16 · /len off",
   view: "/view focus | all",
   transcript: "/transcript",
   log: "/transcript",
@@ -624,6 +683,18 @@ export const USAGE: Readonly<Record<string, string>> = {
   guide: "/guide [topic] · /guide chords · F1",
   fx: "fx <effect> <param> <value> | on | off | preset <name> · fx delay mix 0.3",
   synth: "synth <param> <value> | preset <name> · synth lpf 1200",
+  string:
+    "string <preset> | preset <name> | <param> <value> | presets | reset | off · string koto",
+  rig: "rig clean|crunch|punk|ragged|lead|metal|fuzz|octave|funk|wah|bachata|spring|bassdrive|reese|jangle|alt | reset",
+  stomp:
+    "stomp fuzz|face|od|rat|octave | gain <0-10> tone <0-1> level <dB> | off",
+  head: "head clean|chime|crunch|lead|high|solid|bass | gain bass mid treble presence master <0-10> | gate <dB> | off",
+  cab: "cab 1x12|2x12|4x12|1x10|open|8x10|1x15|di | mic <0-1> | off",
+  keys: "keys <param> <value> | preset <name> | reset | presets · keys hardness 0.3 · keys stretch 0",
+  piano:
+    "piano [grand|ballad|upright|felt|lofi|honkytonk|prepared] · piano ballad",
+  modal:
+    "modal <preset> | <body> | <param> <value> | mallet <name> | reset | off | presets · modal vibes · modal saron · modal ring 3",
   pack: "/pack list | info <name> | use <pack>/<sound> | add <url>",
   kit: "/kit [name] · /kit syn909",
   euclid: "/euclid [voice] · euclid hat 7 16",