@hraness/dawg 0.7.0 → 0.8.0

package/src/agent/range-tools.ts

@@ -0,0 +1,216 @@
+/**
+ * Agent tool for range edits (op1-ux §6.4): `edit_range` builds the same
+ * line the prompt runs (`loop 5-6`, `copy bass 5-6 to 7 x2`, `bars insert
+ * 2 at 3`, `section split chorus at 13`) and applies it through
+ * src/commands/range.ts or src/commands/arrange.ts, so the tool, the typed
+ * command and the menu agree. Its operations are the score diff.
+ *
+ * Bars count from 1, like the prompt and the bar ruler.
+ */
+import { diffScores } from "../../core/diff.ts";
+import { SCORE_LIMITS, type TrackScore } from "../../core/score.ts";
+import {
+  applySectionCommand,
+  loopSpan,
+  parseSectionCommand,
+} from "../commands/arrange.ts";
+import { parseLoopCommand } from "../commands/grammar.ts";
+import { applyRangeCommand, parseRangeCommand } from "../commands/range.ts";
+import type { AgentTool, ToolContext, ToolPlan } from "./tools.ts";
+import { ToolArgumentError } from "./tool-error.ts";
+
+export const RANGE_ACTIONS = [
+  "loop",
+  "unloop",
+  "copy",
+  "move",
+  "clear",
+  "reverse",
+  "insert_bars",
+  "remove_bars",
+  "split",
+  "join",
+] as const;
+
+type RangeAction = (typeof RANGE_ACTIONS)[number];
+
+const bar = (description: string) =>
+  ({
+    type: "integer",
+    minimum: 1,
+    maximum: SCORE_LIMITS.maxBars,
+    description,
+  }) as const;
+
+function whole(value: unknown, what: string, max: number): number {
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > max
+  )
+    throw new ToolArgumentError(`${what} must be a whole number 1..${max}`);
+  return value;
+}
+
+function word(value: unknown, what: string): string {
+  if (typeof value !== "string" || !/^[\w .'-]{1,64}$/u.test(value.trim()))
+    throw new ToolArgumentError(`${what} must be a name`);
+  return value.trim();
+}
+
+/** `5-6`, `5`, or a section name: the range words of the typed command. */
+function rangeWords(args: Record<string, unknown>): string {
+  if (args.section !== undefined) return word(args.section, "section");
+  if (args.fromBar === undefined)
+    throw new ToolArgumentError("give fromBar (and toBar) or section");
+  const from = whole(args.fromBar, "fromBar", SCORE_LIMITS.maxBars);
+  const to =
+    args.toBar === undefined
+      ? from
+      : whole(args.toBar, "toBar", SCORE_LIMITS.maxBars);
+  if (to < from) throw new ToolArgumentError("toBar comes at or after fromBar");
+  return from === to ? `${from}` : `${from}-${to}`;
+}
+
+function trackWord(
+  args: Record<string, unknown>,
+  context: ToolContext,
+): string {
+  if (args.allTracks === true) return "all";
+  const id =
+    args.trackId === undefined
+      ? context.focusedTrackId
+      : word(args.trackId, "trackId");
+  if (!context.score.tracks.some((track) => track.id === id))
+    throw new ToolArgumentError(`no track ${id}`);
+  return id;
+}
+
+/** The typed command a call stands for (what show-me would type). */
+export function rangeToolCommand(
+  args: Record<string, unknown>,
+  context: ToolContext,
+): string {
+  const action = args.action as RangeAction;
+  if (!RANGE_ACTIONS.includes(action))
+    throw new ToolArgumentError(`action must be ${RANGE_ACTIONS.join(", ")}`);
+  switch (action) {
+    case "loop":
+      return `loop ${rangeWords(args)}`;
+    case "unloop":
+      return "loop off";
+    case "copy":
+    case "move": {
+      if (args.toBar === undefined && args.atBar === undefined)
+        throw new ToolArgumentError(`${action} needs atBar, where it lands`);
+      const at = whole(args.atBar, "atBar", SCORE_LIMITS.maxBars);
+      const times =
+        action === "copy" && args.times !== undefined
+          ? ` x${whole(args.times, "times", 64)}`
+          : "";
+      const mode =
+        args.insert === true
+          ? " insert"
+          : action === "copy" && args.merge === true
+            ? " merge"
+            : "";
+      return `${action} ${trackWord(args, context)} ${rangeWords(args)} to ${at}${times}${mode}`;
+    }
+    case "clear":
+    case "reverse":
+      return `${action} ${trackWord(args, context)} ${rangeWords(args)}`;
+    case "insert_bars":
+      return `bars insert ${whole(args.bars, "bars", SCORE_LIMITS.maxBars)} at ${whole(args.atBar, "atBar", SCORE_LIMITS.maxBars)}`;
+    case "remove_bars":
+      return `bars remove ${rangeWords(args)}`;
+    case "split":
+      return `section split ${word(args.section, "section")} at ${whole(args.atBar, "atBar", SCORE_LIMITS.maxBars)}`;
+    case "join":
+      return `section join ${word(args.section, "section")}`;
+  }
+}
+
+function run(
+  line: string,
+  context: ToolContext,
+): { next?: TrackScore; message: string } {
+  const score = context.score;
+  const loop = parseLoopCommand(line);
+  if (loop?.type === "loop-bars") {
+    const result = loopSpan(score, loop.from, loop.to);
+    if (!result.ok) throw new ToolArgumentError(result.message);
+    return { next: result.next, message: result.message };
+  }
+  if (loop?.type === "loop-off")
+    return score.loop
+      ? { next: score.withLoop(null), message: "loop · off · playing the song" }
+      : run("section loop off", context);
+  if (loop?.type === "loop-section")
+    return run(`section loop ${loop.name}`, context);
+  const range = parseRangeCommand(line, score);
+  if (range) {
+    const result = applyRangeCommand(
+      score,
+      { trackId: context.focusedTrackId, playheadBar: 0 },
+      range,
+    );
+    if (!result.ok) throw new ToolArgumentError(result.message);
+    return {
+      ...(result.next ? { next: result.next } : {}),
+      message: result.message,
+    };
+  }
+  const section = parseSectionCommand(line, score);
+  if (!section) throw new ToolArgumentError(`cannot run: ${line}`);
+  const result = applySectionCommand(score, context.focusedTrackId, section);
+  if (!result.ok) throw new ToolArgumentError(result.message);
+  return {
+    ...(result.next ? { next: result.next } : {}),
+    message: result.message,
+  };
+}
+
+export const RANGE_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "edit_range",
+    description:
+      "Edit bar ranges (bars count from 1; a range is fromBar..toBar or a section name). loop sets the loop range playback cycles (no section is made); unloop plays the song. copy copies a track's (or allTracks') notes, automation and clips in the range to atBar, overwriting there (merge keeps what is there; insert shifts later music right), times tiles it end to end. move is copy plus clearing the source. clear empties the range (the bars stay). reverse mirrors it in time. insert_bars adds `bars` empty bars at atBar and moves later sections, clips, automation and tempo points right; remove_bars cuts the range out. split cuts a section in two at atBar; join merges a section with the one after it. Each call is one undo step and runs the same command the prompt does.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: [...RANGE_ACTIONS] },
+        fromBar: bar("first bar of the range"),
+        toBar: bar("last bar of the range (default fromBar)"),
+        section: {
+          type: "string",
+          maxLength: 32,
+          description: "a section as the range (split/join: the section)",
+        },
+        atBar: bar("copy/move: where it lands; insert_bars/split: the bar"),
+        bars: bar("insert_bars: how many"),
+        times: { type: "integer", minimum: 1, maximum: 64 },
+        trackId: {
+          type: "string",
+          maxLength: SCORE_LIMITS.maxIdLength,
+          description: "the track (default: the focused track)",
+        },
+        allTracks: { type: "boolean" },
+        insert: { type: "boolean" },
+        merge: { type: "boolean" },
+      },
+      required: ["action"],
+      additionalProperties: false,
+    },
+    plan(args, context): ToolPlan {
+      const line = rangeToolCommand(args, context);
+      const result = run(line, context);
+      return {
+        kind: "score",
+        operations: result.next ? diffScores(context.score, result.next) : [],
+        trackId: context.focusedTrackId,
+        summary: result.message,
+      };
+    },
+  },
+]);

package/src/agent/show-me.ts

@@ -90,7 +90,7 @@ function cleanLine(line: string): string {
  * quit or change this window's settings, none of which edits the song.
  */
 const WINDOW_ONLY =
-  /^\/(?:help|guide|menu|play|login|logout|auth|model|quit|exit|sessions?|new|showme|status|undo|redo|tracks|euclid|try|record|grid|count-?in|click|chords|theme|motion|view|transcript)\b/i;
+  /^\/(?:help|guide|menu|play|login|logout|auth|model|quit|exit|sessions?|new|showme|status|undo|redo|tracks|euclid|try|record|grid|count-?in|click|chords|theme|motion|view|transcript)\b|^\/?(?:tape|knobs|mix|panes?|pin|unpin|follow|unfollow|audio)(?:\s|$)/i;
 
 /**
  * Whether a complete line is a command the agent runs: one a human could

package/src/agent/tools.ts

@@ -114,6 +114,7 @@ import { STYLE_TOOLS } from "./style-tools.ts";
 import { DRUM_TOOLS } from "./drum-tools.ts";
 import { TIME_TOOLS } from "./time-tools.ts";
 import { SECTION_TOOLS } from "./section-tools.ts";
+import { RANGE_TOOLS } from "./range-tools.ts";
 import { GRANULAR_TOOLS } from "./granular-tools.ts";
 import { RESAMPLE_TOOLS } from "./resample-tool.ts";
 import { VOICE_TOOLS } from "./voice-tools.ts";
@@ -2035,6 +2036,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   ...DRUM_TOOLS,
   ...TIME_TOOLS,
   ...SECTION_TOOLS,
+  ...RANGE_TOOLS,
   ...MEDIA_TOOLS,
   ...PACK_TOOLS,
   ...MASTER_TOOLS,

package/src/agent/xcb-agent.ts

@@ -1,3 +1,4 @@
+import { newId } from "../../core/ids.ts";
 import { GRANULAR_PARAMS } from "../../core/granular.ts";
 import { compositionBrief } from "./brief.ts";
 import { CHORD_PROCESS } from "../../core/chords.ts";
@@ -125,11 +126,9 @@ export async function runTextAgentTurn(
   };
   const tools = options.tools ?? AGENT_TOOLS;
   const catalog = renderToolCatalog(tools);
-  const nonce = Math.random().toString(36).slice(2, 6);
   const newNoteId =
     options.newNoteId ??
-    ((trackId: string, revision: number, index: number) =>
-      `${trackId.slice(0, 40)}-${revision}-${nonce}${index}`);
+    ((trackId: string, _revision: number, _index: number) => newId(trackId));
   const startedAt = Date.now();
   const deadline = turnDeadline(limits.timeoutMs);
   const signal = options.signal

package/src/audio/arrange.ts

@@ -15,6 +15,7 @@ import {
   ScoreValidationError,
   TrackScore,
   type Note,
+  type Section,
   withNoteCap,
 } from "../../core/score.ts";
 import {
@@ -103,8 +104,17 @@ export function sectionCues(
     }));
 }
 
-/** The section playback loops, when `loopSection` names one. */
-export function loopedSection(score: TrackScore) {
+/**
+ * The bars playback loops: the loop range (as an unnamed section with no
+ * mutes or variations), else the section `loopSection` names. A range is
+ * cut to the song's bars; one wholly past the end loops nothing.
+ */
+export function loopedSection(score: TrackScore): Section | undefined {
+  if (score.loop) {
+    const startBar = Math.min(score.loop.startBar, score.bars - 1);
+    const bars = Math.max(1, Math.min(score.loop.bars, score.bars - startBar));
+    return { name: "loop", startBar, bars };
+  }
   return score.loopSection === undefined
     ? undefined
     : findSection(score, score.loopSection);

package/src/audio/audio-command.ts

@@ -0,0 +1,218 @@
+/**
+ * `audio`, `audio out <name|default>`, `audio in <name|default>` and
+ * `audio test`: the typed form of Ctrl-K › Project › audio. One output and
+ * one input; the choice lives in `<config>/audio.json` on this machine.
+ */
+import type { AudioBackendInfo } from "./engine.ts";
+import {
+  audioChoicePath,
+  blipSamples,
+  deviceLabel,
+  deviceSupport,
+  levelMeter,
+  listDevices,
+  matchDevice,
+  measureInput,
+  parseAudioCommand,
+  playOnce,
+  readAudioChoice,
+  writeAudioChoice,
+  type AudioChoice,
+} from "./devices.ts";
+import type { MenuAudioDevices } from "../tui/menu.ts";
+
+export const AUDIO_USAGE =
+  "usage · audio · audio out <name|default> · audio in <name|default> · audio test";
+
+export type AudioCommandContext = Readonly<{
+  info: AudioBackendInfo;
+  env?: Readonly<Record<string, string | undefined>>;
+  /** Where the choice is saved (default `<config>/audio.json`). */
+  path?: string;
+  /** Move this window's playback (the engine's `setDevice`). */
+  setOutput?: (name: string | undefined) => void;
+  /** Injected by tests: no real waiting for the blip, tone and meter. */
+  wait?: (ms: number) => Promise<void>;
+  /** Run the blip without blocking the reply (the default awaits it). */
+  background?: (task: Promise<unknown>) => void;
+}>;
+
+export type AudioCommandResult = Readonly<{
+  ok: boolean;
+  message: string;
+  /** Extra lines for a panel (the device lists, the test result). */
+  lines?: readonly string[];
+}>;
+
+function names(devices: readonly { name: string }[]): string {
+  return devices.length > 0
+    ? devices.map((device) => device.name).join(" · ")
+    : "none found";
+}
+
+/** What Project › audio shows. */
+export function audioMenuState(
+  info: AudioBackendInfo,
+  choice: AudioChoice = readAudioChoice(),
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): MenuAudioDevices {
+  const support = deviceSupport(info);
+  if (support.kind !== "native") {
+    const output =
+      support.kind === "sox"
+        ? ((env.DAWG_AUDIO_DEVICE?.trim() || choice.output) ?? "default")
+        : "default";
+    return {
+      output,
+      input: "default",
+      outputs: [],
+      inputs: [],
+      unavailable:
+        support.kind === "sox"
+          ? "sox cannot list devices · type audio out <name> (sox AUDIODEV) · the native sink lists them"
+          : support.reason,
+    };
+  }
+  const outputs = listDevices(support.library, false);
+  const inputs = listDevices(support.library, true);
+  const override = env.DAWG_AUDIO_DEVICE?.trim();
+  return {
+    output: deviceLabel(override || choice.output, outputs),
+    input: deviceLabel(choice.input, inputs),
+    outputs: outputs.map((device) => device.name),
+    inputs: inputs.map((device) => device.name),
+  };
+}
+
+export async function runAudioCommand(
+  args: string,
+  context: AudioCommandContext,
+): Promise<AudioCommandResult> {
+  const parsed = parseAudioCommand(args);
+  if (!parsed) return { ok: false, message: AUDIO_USAGE };
+  const env = context.env ?? process.env;
+  const path = context.path ?? audioChoicePath(env);
+  const choice = readAudioChoice(path);
+  const support = deviceSupport(context.info);
+  const override = env.DAWG_AUDIO_DEVICE?.trim() || undefined;
+  const overrideNote = override
+    ? ` · DAWG_AUDIO_DEVICE=${override} overrides the output`
+    : "";
+
+  if (parsed.kind === "show") {
+    const state = audioMenuState(context.info, choice, env);
+    const lines = [
+      `output  ${state.output}`,
+      `input   ${state.input}`,
+      `player  ${context.info.backend}`,
+    ];
+    if (state.unavailable) lines.push(state.unavailable);
+    else {
+      lines.push(`outputs ${state.outputs.join(" · ") || "none found"}`);
+      lines.push(`inputs  ${state.inputs.join(" · ") || "none found"}`);
+    }
+    return {
+      ok: true,
+      message: `audio · out ${state.output} · in ${state.input}${overrideNote}`,
+      lines,
+    };
+  }
+
+  if (support.kind === "none") return { ok: false, message: support.reason };
+
+  if (parsed.kind === "set" && parsed.side === "output") {
+    if (support.kind === "sox") {
+      writeAudioChoice("output", parsed.name, path);
+      context.setOutput?.(override ?? parsed.name);
+      return {
+        ok: true,
+        message: `audio out ${parsed.name ?? "default"} · sox plays on AUDIODEV (it cannot list devices; the native sink can)${overrideNote}`,
+      };
+    }
+    const devices = listDevices(support.library, false);
+    const device = parsed.name ? matchDevice(devices, parsed.name) : undefined;
+    if (parsed.name && !device)
+      return {
+        ok: false,
+        message: `no output named "${parsed.name}" · ${names(devices)}`,
+      };
+    writeAudioChoice("output", device?.name, path);
+    const playing = override ?? device?.name;
+    context.setOutput?.(playing);
+    // The soft blip says where sound now comes out.
+    const blip = playOnce(
+      support.library,
+      playing,
+      blipSamples(48_000),
+      48_000,
+      context.wait,
+    ).catch(() => false);
+    if (context.background) context.background(blip);
+    else await blip;
+    return {
+      ok: true,
+      message: `audio out ${deviceLabel(device?.name, devices)}${overrideNote}`,
+    };
+  }
+
+  if (parsed.kind === "set") {
+    if (support.kind === "sox")
+      return {
+        ok: false,
+        message:
+          "choosing an input needs the native sink (it captures by name; sox here only plays)",
+      };
+    const devices = listDevices(support.library, true);
+    const device = parsed.name ? matchDevice(devices, parsed.name) : undefined;
+    if (parsed.name && !device)
+      return {
+        ok: false,
+        message: `no input named "${parsed.name}" · ${names(devices)}`,
+      };
+    writeAudioChoice("input", device?.name, path);
+    return {
+      ok: true,
+      message: `audio in ${deviceLabel(device?.name, devices)} · audio test meters it`,
+    };
+  }
+
+  // audio test: a short tone on the output, then the input's level.
+  if (support.kind === "sox")
+    return {
+      ok: false,
+      message:
+        "audio test needs the native sink (it plays the tone and meters the input)",
+    };
+  const output = override ?? choice.output;
+  const outputs = listDevices(support.library, false);
+  const inputs = listDevices(support.library, true);
+  const played = await playOnce(
+    support.library,
+    output,
+    blipSamples(48_000, 0.4, 440, 0.15),
+    48_000,
+    context.wait,
+  ).catch(() => false);
+  let meter: string;
+  try {
+    const level = await measureInput(
+      support.library,
+      choice.input,
+      1,
+      48_000,
+      context.wait,
+    );
+    meter = levelMeter(level.peakDb);
+  } catch (error) {
+    meter = `could not open (${error instanceof Error ? error.message : String(error)})`;
+  }
+  const lines = [
+    `output  ${deviceLabel(output, outputs)} · ${played ? "tone played" : "could not open"}`,
+    `input   ${deviceLabel(choice.input, inputs)} · peak ${meter}`,
+  ];
+  return {
+    ok: played,
+    message: `audio test · ${lines[0]!.replace(/\s+/, " ")} · ${lines[1]!.replace(/\s+/, " ")}`,
+    lines,
+  };
+}