@hraness/dawg 0.4.0 → 0.5.0

package/src/agent/tools.ts

@@ -7,6 +7,7 @@ import {
   type ScoreOperation,
   type TrackScore,
 } from "../../core/score.ts";
+import { loopTicksOf } from "../../core/tempo.ts";
 import { AVAILABLE_INSTRUMENTS } from "../audio/wav.ts";
 import {
   SYNTH_PRESETS,
@@ -44,9 +45,15 @@ import {
 import { PackError, type PackStore } from "../audio/packs.ts";
 import { RHYTHM_TOOLS } from "./rhythm-tools.ts";
 import { CHORD_TOOLS } from "./chord-tools.ts";
+import { EXPRESSION_TOOLS } from "./expression-tools.ts";
+import { TUNING_TOOLS } from "./tuning-tools.ts";
+import { MASTER_TOOLS } from "./master-tools.ts";
 import { DRUM_TOOLS } from "./drum-tools.ts";
+import { TIME_TOOLS } from "./time-tools.ts";
+import { SECTION_TOOLS } from "./section-tools.ts";
 import type { MediaResult, MediaRunContext } from "../media/types.ts";
 import { pitchToMidi } from "./ops.ts";
+import { TUNING_LIMITS } from "../../core/tuning.ts";
 import {
   DRUM_VOICES,
   drumVoicePitch,
@@ -244,6 +251,12 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
                 description: "Length in beats",
               },
               velocity: { type: "number", minimum: 0, maximum: 1 },
+              cents: {
+                type: "number",
+                minimum: -TUNING_LIMITS.maxNoteCents,
+                maximum: TUNING_LIMITS.maxNoteCents,
+                description: "Detune from the tuned pitch (microtones)",
+              },
             },
             required: ["pitch", "start", "duration"],
             additionalProperties: false,
@@ -262,6 +275,10 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         const start = number(note, "start", { min: 0 });
         const duration = number(note, "duration", { min: 0, exclusive: true });
         const velocity = optionalNumber(note, "velocity", { min: 0, max: 1 });
+        const cents = optionalNumber(note, "cents", {
+          min: -TUNING_LIMITS.maxNoteCents,
+          max: TUNING_LIMITS.maxNoteCents,
+        });
         return {
           type: "addNote",
           note: {
@@ -271,6 +288,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
             durationTicks: Math.max(1, Math.round(duration * tpb)),
             pitch: pitch(note.pitch, `notes[${index}].pitch`),
             velocity: velocity ?? 0.8,
+            ...(cents ? { cents } : {}),
           },
         };
       });
@@ -322,7 +340,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   {
     name: "update_notes",
     description:
-      "Move, resize, transpose, or re-velocity existing notes by id. Times are in beats.",
+      "Move, resize, transpose, re-velocity or detune existing notes by id. Times are in beats.",
     parameters: {
       type: "object",
       properties: {
@@ -343,6 +361,12 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
                 ],
               },
               velocity: { type: "number", minimum: 0, maximum: 1 },
+              cents: {
+                type: "number",
+                minimum: -TUNING_LIMITS.maxNoteCents,
+                maximum: TUNING_LIMITS.maxNoteCents,
+                description: "Detune from the tuned pitch; 0 clears it",
+              },
             },
             required: ["noteId"],
             additionalProperties: false,
@@ -378,6 +402,11 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
             max: 1,
           });
           if (velocity !== undefined) patch.velocity = velocity;
+          const cents = optionalNumber(update, "cents", {
+            min: -TUNING_LIMITS.maxNoteCents,
+            max: TUNING_LIMITS.maxNoteCents,
+          });
+          if (cents !== undefined) patch.cents = cents;
           if (Object.keys(patch).length === 0)
             throw new ToolArgumentError(`updates[${index}] changes nothing`);
           return { type: "updateNote", noteId, patch };
@@ -915,7 +944,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
           `track ${trackId} is ${track.instrument}, not a drum kit; set_instrument kit or create a kit track`,
         );
       const tpb = context.score.ticksPerBeat;
-      const loopBeats = context.score.bars * context.score.beatsPerBar;
+      const loopBeats = loopTicksOf(context.score) / tpb;
       const voiceOf = (value: unknown, label: string) => {
         const voice =
           typeof value === "string" ? parseDrumVoice(value) : undefined;
@@ -1350,9 +1379,14 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   ...RHYTHM_TOOLS,
   ...CHORD_TOOLS,
+  ...EXPRESSION_TOOLS,
+  ...TUNING_TOOLS,
   ...DRUM_TOOLS,
+  ...TIME_TOOLS,
+  ...SECTION_TOOLS,
   ...MEDIA_TOOLS,
   ...PACK_TOOLS,
+  ...MASTER_TOOLS,
   // Looks tools up at call time, so it can plan any of the above.
   previewSoundTool((name) => findAgentTool(name)),
 ] satisfies AgentTool[]);

package/src/agent/tuning-tools.ts

@@ -0,0 +1,301 @@
+/**
+ * Agent tools for tunings and scales: `set_tuning` and `set_scale`. Both
+ * build the same `/tuning` and `/scale` commands the prompt and the menu
+ * run (src/commands/tuning.ts), so every surface validates alike.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { ScoreOperation, TrackScore } from "../../core/score.ts";
+import { TUNING_LIMITS, TUNING_MAPS, type Tuning } from "../../core/tuning.ts";
+import {
+  applyTuningCommand,
+  parseTuningCommand,
+  type ProjectRead,
+  type TuningResult,
+} from "../commands/tuning.ts";
+import { resolveReadPath, WorkspaceError } from "./workspace.ts";
+import type { AgentTool, ScorePlan, ToolContext } from "./tools.ts";
+
+class TuningToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+const MAX_TABLE = 128;
+
+/** The `/tuning …` arguments one set_tuning call stands for. */
+export function tuningCommandsFor(args: Record<string, unknown>): string[] {
+  const target = args.target === undefined ? "song" : args.target;
+  if (target !== "song" && target !== "track")
+    throw new TuningToolError("target must be song or track");
+  const prefix = target === "track" ? "tuning track" : "tuning";
+  if (args.off === true) return [`${prefix} off`];
+  const commands: string[] = [];
+  const tables = ["name", "edo", "ratios", "cents", "scl"].filter(
+    (field) => args[field] !== undefined,
+  );
+  if (tables.length > 1)
+    throw new TuningToolError(
+      `give one of name, edo, ratios, cents or scl (got ${tables.join(", ")})`,
+    );
+  const word = (value: unknown, field: string): string => {
+    if (typeof value !== "string" || !/^[^\s]{1,256}$/.test(value))
+      throw new TuningToolError(`${field} must be one word`);
+    return value;
+  };
+  const table = tables[0];
+  if (table === "name") commands.push(`${prefix} ${word(args.name, "name")}`);
+  else if (table === "edo") {
+    const edo = args.edo;
+    if (
+      typeof edo !== "number" ||
+      !Number.isInteger(edo) ||
+      edo < 1 ||
+      edo > TUNING_LIMITS.maxEdo
+    )
+      throw new TuningToolError(`edo must be 1..${TUNING_LIMITS.maxEdo}`);
+    commands.push(`${prefix} edo ${edo}`);
+  } else if (table === "ratios" || table === "cents") {
+    const list = args[table];
+    if (!Array.isArray(list) || list.length < 1 || list.length > MAX_TABLE)
+      throw new TuningToolError(`${table} must list 1..${MAX_TABLE} steps`);
+    const items = list.map((item, index) => {
+      if (table === "cents" && typeof item === "number" && isFinite(item))
+        return String(item);
+      return word(
+        typeof item === "number" ? String(item) : item,
+        `${table}[${index}]`,
+      );
+    });
+    commands.push(`${prefix} ${table} ${items.join(" ")}`);
+  } else if (table === "scl") {
+    const scl = word(args.scl, "scl");
+    commands.push(
+      args.kbm !== undefined
+        ? `${prefix} scl ${scl} kbm ${word(args.kbm, "kbm")}`
+        : `${prefix} scl ${scl}`,
+    );
+  }
+  if (table !== "scl" && args.kbm !== undefined)
+    commands.push(
+      args.kbm === null
+        ? `${prefix} kbm off`
+        : `${prefix} kbm ${word(args.kbm, "kbm")}`,
+    );
+  if (args.ref !== undefined) {
+    if (args.ref === null) commands.push(`${prefix} ref off`);
+    else if (typeof args.ref === "number" && isFinite(args.ref))
+      commands.push(`${prefix} ref ${args.ref}`);
+    else throw new TuningToolError("ref must be a number of Hz or null");
+  }
+  if (args.root !== undefined)
+    commands.push(
+      `${prefix} root ${args.root === null ? "auto" : word(String(args.root), "root")}`,
+    );
+  if (args.map !== undefined) {
+    if (!TUNING_MAPS.includes(args.map as never))
+      throw new TuningToolError(`map must be ${TUNING_MAPS.join(" or ")}`);
+    commands.push(`${prefix} map ${String(args.map)}`);
+  }
+  if (commands.length === 0)
+    throw new TuningToolError(
+      "give a tuning (name, edo, ratios, cents or scl), ref, root, map or off",
+    );
+  return commands;
+}
+
+/** Runs `commands` in order and returns the operations they produced. */
+function planCommands(
+  score: TrackScore,
+  trackId: string,
+  commands: readonly string[],
+  read: ProjectRead,
+): ScorePlan {
+  let next = score;
+  const operations: ScoreOperation[] = [];
+  const messages: string[] = [];
+  for (const text of commands) {
+    const command = parseTuningCommand(text);
+    if (!command) throw new TuningToolError(`cannot read ${text}`);
+    const result: TuningResult = applyTuningCommand(
+      next,
+      trackId,
+      command,
+      read,
+    );
+    if (!result.ok || !result.next) throw new TuningToolError(result.message);
+    operations.push(operationOf(result, trackId));
+    messages.push(result.message);
+    next = result.next;
+  }
+  return {
+    kind: "score",
+    operations,
+    summary: messages.at(-1) ?? "tuning",
+    trackId,
+  };
+}
+
+function operationOf(result: TuningResult, trackId: string): ScoreOperation {
+  const payload = result.payload ?? {};
+  if (result.kind === "score.tuning")
+    return {
+      type: "setTuning",
+      tuning: (payload.tuning as Tuning | null | undefined) ?? null,
+    };
+  if (result.kind === "score.track")
+    return {
+      type: "updateTrack",
+      trackId,
+      patch: (payload.patch as { tuning: Tuning | null }) ?? {},
+    };
+  if (result.kind === "score.key")
+    return { type: "setKey", key: (payload.key as string | null) ?? null };
+  throw new TuningToolError(`unexpected result ${result.kind ?? ""}`);
+}
+
+function trackFor(args: Record<string, unknown>, context: ToolContext): string {
+  const id = args.trackId ?? context.focusedTrackId;
+  if (typeof id !== "string" || !context.score.tracks.some((t) => t.id === id))
+    throw new TuningToolError(`no track ${String(id)}`);
+  return id;
+}
+
+const SET_TUNING: AgentTool = {
+  name: "set_tuning",
+  description:
+    "Set the song tuning (every track follows it) or one track's own tuning: a library tuning by name, n-EDO, just ratios, cents, or a Scala .scl/.kbm file in the project; plus A4 reference, root key and key mapping. off returns to 12-TET (track: follows the song). Note-level detune is add_notes cents.",
+  parameters: {
+    type: "object",
+    properties: {
+      target: { type: "string", enum: ["song", "track"] },
+      trackId: { type: "string", description: "track target; default focused" },
+      name: {
+        type: "string",
+        description:
+          "19-edo, 24-edo, 31-edo, pythagorean, just, 7-limit, well-tuned-piano, pelog, slendro, rast, bayati, yaman…",
+      },
+      edo: { type: "integer", minimum: 1, maximum: TUNING_LIMITS.maxEdo },
+      ratios: {
+        type: "array",
+        items: { type: "string" },
+        maxItems: MAX_TABLE,
+        description:
+          'degrees 1..n, last is the period: ["9/8","5/4","3/2","2/1"]',
+      },
+      cents: {
+        type: "array",
+        items: { type: "number" },
+        maxItems: MAX_TABLE,
+        description: "degrees 1..n in cents, last is the period (1200)",
+      },
+      scl: { type: "string", description: "project path to a .scl file" },
+      kbm: {
+        type: ["string", "null"],
+        description: "project path to a .kbm keyboard map; null removes it",
+      },
+      ref: {
+        type: ["number", "null"],
+        minimum: TUNING_LIMITS.minRefHz,
+        maximum: TUNING_LIMITS.maxRefHz,
+        description: "A4 in Hz (440); null resets",
+      },
+      root: {
+        type: ["string", "null"],
+        description: 'key of degree 0 ("D4"); null follows the song key',
+      },
+      map: {
+        type: "string",
+        enum: TUNING_MAPS,
+        description:
+          "linear: one key per step · nearest: 12 keys to nearest step",
+      },
+      off: { type: "boolean" },
+    },
+    additionalProperties: false,
+  },
+  plan(args, context) {
+    const trackId = trackFor(args, context);
+    const commands = tuningCommandsFor(args);
+    const needsFiles = args.scl !== undefined || typeof args.kbm === "string";
+    const current =
+      args.target === "track"
+        ? context.score.tracks.find((t) => t.id === trackId)?.tuning
+        : context.score.tuning;
+    if (!needsFiles && !current?.scl && !current?.kbm)
+      return planCommands(context.score, trackId, commands, () => undefined);
+    return {
+      kind: "prepare",
+      summary: commands.join(" · "),
+      async run(host) {
+        const files = new Map<string, string>();
+        if (host.workspace) {
+          const paths = [args.scl, args.kbm, current?.scl, current?.kbm].filter(
+            (path): path is string => typeof path === "string",
+          );
+          for (const path of paths) {
+            try {
+              const resolved = await resolveReadPath(
+                { root: host.workspace.root, trackSlug: "" },
+                path,
+              );
+              files.set(path, await readFile(resolved.real, "utf8"));
+            } catch (error) {
+              if (!(error instanceof WorkspaceError)) throw error;
+            }
+          }
+        }
+        return planCommands(context.score, trackId, commands, (path) =>
+          files.get(path),
+        );
+      },
+    };
+  },
+};
+
+const SET_SCALE: AgentTool = {
+  name: "set_scale",
+  description:
+    "Set the song key and scale: a church mode, harmonic or melodic minor, pentatonic, blues, maqam (hijaz, bayati), raga (yaman, bhairav, kafi…) or a Messiaen mode. Chords, play-mode keys and scale snapping follow it. Scales with microtones or just intonation pair with set_tuning name=<scale>.",
+  parameters: {
+    type: "object",
+    properties: {
+      tonic: {
+        type: "string",
+        description: '"C", "F#", "Eb"; default song tonic',
+      },
+      scale: {
+        type: "string",
+        description:
+          "dorian, harmonic-minor, minor-pentatonic, blues, hijaz, bayati, yaman, bhairav, kafi, messiaen-3…",
+      },
+    },
+    required: ["scale"],
+    additionalProperties: false,
+  },
+  plan(args, context) {
+    const scale = args.scale;
+    if (typeof scale !== "string" || !/^[a-z0-9-]{1,32}$/i.test(scale))
+      throw new TuningToolError("scale must be a scale name");
+    const tonic = args.tonic;
+    if (
+      tonic !== undefined &&
+      (typeof tonic !== "string" || !/^[a-g][#b]?$/i.test(tonic))
+    )
+      throw new TuningToolError('tonic must be a note name like "D" or "Eb"');
+    const command = tonic ? `scale ${tonic} ${scale}` : `scale ${scale}`;
+    return planCommands(
+      context.score,
+      context.focusedTrackId,
+      [command],
+      () => undefined,
+    );
+  },
+};
+
+export const TUNING_TOOLS: readonly AgentTool[] = Object.freeze([
+  SET_TUNING,
+  SET_SCALE,
+]);

package/src/agent/xcb-agent.ts

@@ -46,12 +46,14 @@ export const TEXT_AGENT_SYSTEM_PROMPT = [
   "Times are in beats from the loop start (0-based). Keep notes inside loopBeats unless you extend the loop first.",
   "Prefer a few well-formed ops (one add_notes op per track part) over many tiny ones.",
   'For drums, create a track with instrument "kit" and prefer set_rhythm (Euclidean rows: pulses over steps, rotate, repeats for rolls, accent, probability, swing) so the beat stays editable as parameters; for a genre groove start from apply_drum_pattern (list_drum_patterns) and pick a sound with set_drum_kit; use add_drums only for one-off fills. Drum pitches select voices, so do not use add_notes for beats.',
+  "Song structure: list_sections shows named sections (bars count from 1); edit_section marks, adds, duplicates, moves, renames, deletes, mutes, varies (transpose/gain) and loops them; set_form sets the play order with repeats (intro verse chorus*2 outro); add_transition generates builds (riser, snare roll, filter sweep, uplifter), drops (cut plus impact) and drum fills at section boundaries.",
   CHORD_PROCESS,
   "Synth voices: set_synth shapes a synth track with Strudel params (ADSR, lpf/lpenv filter envelopes, fm/fmh, supersaw unison/detune, vib, penv, noise; z_* ZzFX sounds take slide/pitchJump/lfo/zcrush…) or a preset (pad lead pluck bass keys bell…).",
   "Sampler voices: set_sample sets Strudel sample controls per voice (begin end speed unit loop loopBegin loopEnd clip/legato fit loopAt accelerate squiz cut); splice = slices with fit.",
   "Effects (set_fx; set_effects and set_automation): the brief's effects list is the fixed chain order with each effect's simple params. set_fx turns an effect on with good defaults, loads a preset or sets params by dawg or Strudel name. Lanes: volume, pan, filter, resonance, delay-feedback, delay-mix, wt and <effect>-<param> (e.g. autofilter-cutoff).",
   "Previewing: preview_sound renders a track, or candidate sound tool calls (changes: [{tool, args}]), without committing, returns loudness, brightness and a comparison, and plays it once in the user's window. Use it when choosing between sounds (tables, presets, effect amounts), say how it sounds, then commit with the normal tools.",
   "Wavetable synth: set_wavetable picks a table (built-ins offline, Strudel wt_ sets fetched once) and scans it by position wt.",
+  "Mastering: set_master sets the song master and loudness target; measure_mix reports LUFS, true peak, balance and correlation. Master only when asked for loudness or a finished sound, and measure before and after.",
   'Reply with exactly one JSON object and nothing else, shaped {"ops":[{"tool":"<tool name>","args":{...}}],"say":"<one short sentence describing the musical change>","done":true}.',
   'Set "done":false only if you need to see the results of these ops before continuing; you will then get each op\'s result and can send more ops.',
   "If an op was rejected, read its diagnostic and either send a corrected op or stop with done:true.",