@hraness/dawg 0.4.1 → 0.6.0

package/src/commands/master.ts

@@ -0,0 +1,361 @@
+/**
+ * The `master` prompt command: the song master chain (core/master.ts) on the
+ * summed mix, and its loudness.
+ *
+ *   master                                show the chain and target
+ *   master <unit>                         list a unit's parameters and presets
+ *   master <unit> on|off                  a unit with its defaults, or off
+ *   master <unit> reset                   a unit back to its defaults (stays on)
+ *   master <unit> preset <name>           load a unit preset
+ *   master <unit> <param> <value> […]     set parameters (turns the unit on)
+ *   master target <lufs>|<name>|off       integrated loudness target
+ *   master <name>                         shorthand for `master target <name>`
+ *   master measure                        render and measure the mix
+ *   master off                            remove the whole master
+ *
+ * Units run in a fixed order: eq, glue, tape, width, limiter. A named target
+ * (streaming, club, loud, …) also turns the limiter on at that target's
+ * ceiling. Each command is one `setMaster` revision and one undo step.
+ */
+import {
+  LOUDNESS_TARGET_NAMES,
+  LOUDNESS_TARGETS,
+  MASTER_LIMITS,
+  MASTER_PRESETS,
+  MASTER_SPECS,
+  MASTER_UNITS,
+  describeMaster,
+  isLoudnessTargetName,
+  isMasterUnit,
+  masterDefaults,
+  normalizeMaster,
+  type LoudnessTargetName,
+  type MasterUnit,
+  type SongMaster,
+} from "../../core/master.ts";
+import { FxValidationError } from "../../core/params.ts";
+import { ScoreValidationError, type TrackScore } from "../../core/score.ts";
+import type { MixMeasurement } from "../audio/loudness.ts";
+import type { MasterReport } from "../audio/master.ts";
+import { parseParamValue } from "./fx.ts";
+
+export type MasterCommand =
+  | { type: "master-list" }
+  | { type: "master-off" }
+  | { type: "master-measure" }
+  | { type: "master-show"; unit: MasterUnit }
+  | { type: "master-unit"; unit: MasterUnit; on: boolean }
+  /** Like `fx <effect> reset`: the unit's defaults, kept on. */
+  | { type: "master-reset"; unit: MasterUnit }
+  | { type: "master-preset"; unit: MasterUnit; preset: string }
+  | {
+      type: "master-set";
+      unit: MasterUnit;
+      values: Readonly<Record<string, number | string | boolean>>;
+    }
+  /** `null` clears the target; a name also sets the limiter's ceiling. */
+  | {
+      type: "master-target";
+      lufs: number | null;
+      name?: LoudnessTargetName;
+      /** The positive number typed, read as negative LUFS (`14` → -14). */
+      flipped?: number;
+    };
+
+/** Platform names that mean the `streaming` target. */
+const STREAMING_ALIASES = new Set([
+  "spotify",
+  "youtube",
+  "tidal",
+  "amazon",
+  "deezer",
+  "soundcloud",
+]);
+
+export function parseMasterCommand(prompt: string): MasterCommand | undefined {
+  const words = prompt
+    .trim()
+    .split(/\s+/)
+    .map((word) => word.toLowerCase());
+  if (words[0] !== "master" && words[0] !== "/master") return undefined;
+  if (prompt.length > 1_024) return undefined;
+  const rest = words.slice(1);
+  if (rest.length === 0) return { type: "master-list" };
+  const head = rest[0]!;
+  if (rest.length === 1 && (head === "off" || head === "reset"))
+    return { type: "master-off" };
+  if (rest.length === 1 && (head === "measure" || head === "meter"))
+    return { type: "master-measure" };
+  if (rest.length === 1 && isLoudnessTargetName(head)) return target(head);
+  // `master spotify` and friends: the streaming target.
+  if (rest.length === 1 && STREAMING_ALIASES.has(head))
+    return target("streaming");
+  // `master on` turns the master on the way most people mean it: the
+  // streaming target with its limiter (`master glue on` turns on one unit).
+  if (rest.length === 1 && head === "on") return target("streaming");
+  // `master -14` is `master target -14`.
+  if (rest.length === 1 && /^[-+]?\d+(?:\.\d+)?$/.test(head))
+    return target(head);
+  if (head === "target" || head === "lufs" || head === "normalize")
+    return rest.length === 2 ? target(rest[1]!) : undefined;
+  if (!isMasterUnit(head)) return undefined;
+  const unit = head;
+  if (rest.length === 1) return { type: "master-show", unit };
+  if (rest.length === 2 && rest[1] === "reset")
+    return { type: "master-reset", unit };
+  if (rest.length === 2 && (rest[1] === "on" || rest[1] === "off"))
+    return { type: "master-unit", unit, on: rest[1] === "on" };
+  // An unknown preset name still parses, so the reply can list the real ones.
+  if (rest[1] === "preset")
+    return rest.length === 3
+      ? { type: "master-preset", unit, preset: rest[2]! }
+      : undefined;
+  if (rest.length === 2 && isMasterPreset(unit, rest[1]!))
+    return { type: "master-preset", unit, preset: rest[1]! };
+  const pairs = rest.slice(1);
+  if (pairs.length % 2 !== 0) return undefined;
+  const values: Record<string, number | string | boolean> = {};
+  const params = MASTER_SPECS[unit].params;
+  for (let index = 0; index < pairs.length; index += 2) {
+    const name = pairs[index]!;
+    const spec = Object.prototype.hasOwnProperty.call(params, name)
+      ? params[name]
+      : undefined;
+    if (!spec) return undefined;
+    const raw = pairs[index + 1]!;
+    // An out-of-range number still parses, so validation can name the range.
+    const value =
+      parseParamValue(spec, raw) ??
+      (/^[-+]?\d+(?:\.\d+)?$/.test(raw) ? Number(raw) : undefined);
+    if (value === undefined) return undefined;
+    values[name] = value;
+  }
+  return { type: "master-set", unit, values };
+}
+
+/** Own preset names only: `constructor` and friends are not presets. */
+export function isMasterPreset(unit: MasterUnit, name: string): boolean {
+  return Object.hasOwn(MASTER_PRESETS[unit], name);
+}
+
+function target(word: string): MasterCommand | undefined {
+  if (word === "off" || word === "none")
+    return { type: "master-target", lufs: null };
+  if (isLoudnessTargetName(word))
+    return {
+      type: "master-target",
+      lufs: LOUDNESS_TARGETS[word].lufs,
+      name: word,
+    };
+  if (!/^[-+]?\d+(?:\.\d+)?$/.test(word)) return undefined;
+  // `target 14` means -14 LUFS: loudness targets are always negative, and
+  // the reply says so. Out of range still parses, so the reply names it.
+  const value = Number(word);
+  return value > 0
+    ? { type: "master-target", lufs: -value, flipped: value }
+    : { type: "master-target", lufs: -Math.abs(value) };
+}
+
+export type MasterResult = Readonly<{
+  ok: boolean;
+  message: string;
+  next?: TrackScore;
+  kind?: string;
+  payload?: Record<string, unknown>;
+}>;
+
+/** The master after one command, before validation. */
+export function nextMaster(
+  master: SongMaster | undefined,
+  command: MasterCommand,
+): Record<string, unknown> | undefined {
+  const draft: Record<string, unknown> = { ...master };
+  switch (command.type) {
+    case "master-list":
+    case "master-measure":
+    case "master-show":
+      return master;
+    case "master-reset":
+      draft[command.unit] = masterDefaults(command.unit);
+      return draft;
+    case "master-off":
+      return undefined;
+    case "master-unit":
+      if (command.on) draft[command.unit] ??= masterDefaults(command.unit);
+      else delete draft[command.unit];
+      return draft;
+    case "master-preset":
+      if (!isMasterPreset(command.unit, command.preset)) return master;
+      draft[command.unit] = {
+        ...masterDefaults(command.unit),
+        ...MASTER_PRESETS[command.unit][command.preset],
+      };
+      return draft;
+    case "master-set":
+      draft[command.unit] = {
+        ...(master?.[command.unit] ?? masterDefaults(command.unit)),
+        ...command.values,
+      };
+      return draft;
+    case "master-target":
+      if (command.lufs === null) delete draft.target;
+      else draft.target = command.lufs;
+      if (command.name) {
+        const named: { ceiling: number; limiter?: string } =
+          LOUDNESS_TARGETS[command.name];
+        draft.limiter = {
+          ...(master?.limiter ?? masterDefaults("limiter")),
+          ...(named.limiter ? MASTER_PRESETS.limiter[named.limiter] : {}),
+          ceiling: named.ceiling,
+        };
+      }
+      return draft;
+  }
+}
+
+export function applyMasterCommand(
+  score: TrackScore,
+  command: MasterCommand,
+): MasterResult {
+  if (command.type === "master-list")
+    return { ok: true, message: masterSummary(score.master) };
+  if (command.type === "master-measure")
+    return { ok: false, message: "master measure needs a render" };
+  if (command.type === "master-show")
+    return { ok: true, message: unitSummary(command.unit, score.master) };
+  if (
+    command.type === "master-preset" &&
+    !isMasterPreset(command.unit, command.preset)
+  )
+    return {
+      ok: false,
+      message: `master ${command.unit} · no preset ${command.preset} · presets ${Object.keys(MASTER_PRESETS[command.unit]).join(" ")}`,
+    };
+  let next: TrackScore;
+  try {
+    const master = normalizeMaster(nextMaster(score.master, command)) ?? null;
+    next = score.withMaster(master);
+  } catch (error) {
+    if (
+      error instanceof ScoreValidationError ||
+      error instanceof FxValidationError
+    )
+      return {
+        ok: false,
+        message: `master · ${error.message.replace(/^master\s+/, "")}`,
+      };
+    throw error;
+  }
+  if (sameMaster(score.master, next.master))
+    return { ok: true, message: masterSummary(score.master) };
+  const parts = [`master · ${describeMaster(next.master)}`];
+  if (command.type === "master-target" && command.flipped !== undefined)
+    parts.push(`read ${command.flipped} as ${-command.flipped} LUFS`);
+  if (
+    next.master?.target !== undefined &&
+    !next.master.limiter &&
+    next.master.target > -16
+  )
+    parts.push(
+      `no limiter: the gain stops at ${MASTER_LIMITS.safeCeiling} dBTP · master limiter on pushes harder`,
+    );
+  return {
+    ok: true,
+    message: parts.join(" · "),
+    next,
+    kind: "score.master",
+    payload: { master: next.master ?? null },
+  };
+}
+
+function sameMaster(a: SongMaster | undefined, b: SongMaster | undefined) {
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+
+/** `master · off · units eq glue …` or the chain with its target. */
+export function masterSummary(master: SongMaster | undefined): string {
+  if (!master)
+    return `master · off · units ${MASTER_UNITS.join(" ")} · targets ${LOUDNESS_TARGET_NAMES.join(" ")}`;
+  return `master · ${describeMaster(master)}`;
+}
+
+/**
+ * One unit for `master <unit>`: on or off, then every parameter with its
+ * current (or default) value, unit and range, then the presets.
+ */
+export function unitSummary(unit: MasterUnit, master?: SongMaster): string {
+  const values = master?.[unit];
+  const params = Object.entries(MASTER_SPECS[unit].params).map(
+    ([name, spec]) => {
+      const value = values?.[name] ?? spec.default;
+      if (spec.kind === "number")
+        return `${name} ${formatValue(value)}${spec.unit ? ` ${spec.unit}` : ""} (${formatValue(spec.min)}..${formatValue(spec.max)})`;
+      if (spec.kind === "enum")
+        return `${name} ${String(value)} (${spec.values.join("|")})`;
+      return `${name} ${value ? "on" : "off"} (on|off)`;
+    },
+  );
+  return [
+    `master ${unit} · ${values ? "on" : "off"}`,
+    ...params,
+    `presets ${Object.keys(MASTER_PRESETS[unit]).join(" ")}`,
+  ].join(" · ");
+}
+
+function formatValue(value: number | string | boolean): string {
+  return typeof value === "number"
+    ? String(Math.round(value * 100) / 100)
+    : String(value);
+}
+
+const fixed = (value: number, digits = 1) =>
+  Number.isFinite(value) ? value.toFixed(digits) : "-∞";
+
+/** `-14.0 LUFS · -1.0 dBTP`: the compact meter. */
+export function loudnessLine(
+  loudness: Readonly<{
+    integrated: number;
+    truePeak: number;
+    target?: number;
+    reached?: boolean;
+  }>,
+): string {
+  const line = `${fixed(loudness.integrated)} LUFS · ${fixed(loudness.truePeak)} dBTP`;
+  if (loudness.target === undefined) return line;
+  return loudness.reached
+    ? `${line} · target ${fixed(loudness.target)} reached`
+    : `${line} · target ${fixed(loudness.target)} missed`;
+}
+
+/**
+ * One line for `master measure` and `dawg render`: loudness, range, peaks,
+ * the target outcome, then balance and stereo.
+ */
+export function measurementLine(
+  mix: MixMeasurement,
+  report?: MasterReport,
+): string {
+  const { loudness } = mix;
+  const parts = [
+    `${fixed(loudness.integrated)} LUFS`,
+    `momentary max ${fixed(loudness.momentaryMax)}`,
+    `short-term max ${fixed(loudness.shortTermMax)}`,
+    `LRA ${fixed(loudness.range)} LU`,
+    `${fixed(loudness.truePeak)} dBTP`,
+    `PLR ${fixed(mix.plr)}`,
+  ];
+  if (report?.target !== undefined && !Number.isFinite(report.integrated))
+    parts.push(`target ${fixed(report.target)} not applied · silent`);
+  else if (report?.target !== undefined)
+    parts.push(
+      report.reached
+        ? `target ${fixed(report.target)} reached`
+        : `target ${fixed(report.target)} missed by ${fixed(Math.abs(report.target - report.integrated))} LU${report.integrated < report.target ? " (add master tape or a faster limiter release)" : ""}`,
+    );
+  const bands = Object.entries(mix.bands)
+    .map(([name, db]) => `${name} ${fixed(db, 0)}`)
+    .join(" ");
+  parts.push(`bands ${bands} dB`);
+  parts.push(`correlation ${fixed(mix.correlation, 2)}`);
+  return parts.join(" · ");
+}

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 },
+  };
+}

package/src/commands/music.ts

@@ -33,6 +33,7 @@ import {
   type NoteInput,
   type TrackScore,
 } from "../../core/score.ts";
+import { loopTicksOf } from "../../core/tempo.ts";
 import {
   drumVoiceForPitch,
   drumVoicePitch,
@@ -383,7 +384,11 @@ export function applyMusicCommand(
   const beats =
     command.type === "drum-hits"
       ? command.beats
-      : everyBeats(command.from, command.step, score.bars * score.beatsPerBar);
+      : everyBeats(
+          command.from,
+          command.step,
+          loopTicksOf(score) / score.ticksPerBeat,
+        );
   if (beats.length > MAX_PATTERN_HITS)
     return { ok: false, message: `pattern exceeds ${MAX_PATTERN_HITS} hits` };
   const pitch = drumVoicePitch(command.voice);