@hraness/dawg 0.3.0 → 0.4.0

package/src/agent/preview-tool.ts

@@ -0,0 +1,270 @@
+/**
+ * `preview_sound`: render a short snippet of a track, or of a candidate
+ * change to it, without committing anything. The candidate is a list of
+ * ordinary sound tool calls (`set_fx`, `set_synth`, `set_wavetable`, …),
+ * planned by those same tools against a copy of the score, so what the
+ * agent hears is exactly what committing them would produce.
+ *
+ * The snippet is the audition loop's score (`previewScore`): the track's
+ * own notes over at most four bars, or a short phrase by role. It renders
+ * through the normal renderer, so every effect, bus and impulse response
+ * sounds as in the song. The result carries loudness, peak and spectral
+ * centroid for the committed and the candidate sound, and a one-line
+ * description. When a TUI is attached the host plays the candidate once.
+ */
+import { applyScoreOperations } from "../../core/diff.ts";
+import { SCORE_LIMITS, type TrackScore } from "../../core/score.ts";
+import {
+  MAX_PREVIEW_BARS,
+  analyzePcm,
+  describeSound,
+  previewScore,
+  type SoundStats,
+} from "../audio/preview.ts";
+import { renderScorePcm, type RenderedAudio } from "../audio/wav.ts";
+import type {
+  ActionContext,
+  AgentTool,
+  ToolContext,
+  ToolPlan,
+} from "./tools.ts";
+
+/** Tools a candidate may use: the ones that change how a track sounds. */
+export const PREVIEWABLE_TOOLS: readonly string[] = Object.freeze([
+  "set_instrument",
+  "set_mix",
+  "set_automation",
+  "set_fx",
+  "set_synth",
+  "set_sample",
+  "set_effects",
+  "set_wavetable",
+  "set_drum_kit",
+  "use_sound",
+]);
+
+const MAX_CHANGES = 8;
+
+/** How the host renders and plays a preview; both optional. */
+export type PreviewHost = Readonly<{
+  /** Render a preview score (the host adds decoded samples); default in-thread. */
+  render?: (score: TrackScore) => Promise<RenderedAudio> | RenderedAudio;
+  /** Play the snippet once; returns false when nothing could sound. */
+  play?: (audio: RenderedAudio) => boolean | Promise<boolean>;
+}>;
+
+/** Thrown for a candidate the tool refuses; nothing is rendered. */
+export class PreviewToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PreviewToolError";
+  }
+}
+
+type Change = Readonly<{ tool: string; args: Record<string, unknown> }>;
+
+function parseChanges(value: unknown): Change[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value))
+    throw new PreviewToolError("changes must be a list");
+  if (value.length > MAX_CHANGES)
+    throw new PreviewToolError(`at most ${MAX_CHANGES} changes`);
+  return value.map((entry, index) => {
+    const item = entry as { tool?: unknown; args?: unknown } | null;
+    if (!item || typeof item.tool !== "string")
+      throw new PreviewToolError(`changes[${index}].tool is required`);
+    if (!PREVIEWABLE_TOOLS.includes(item.tool))
+      throw new PreviewToolError(
+        `changes[${index}]: ${item.tool} cannot be previewed; use ${PREVIEWABLE_TOOLS.join(", ")}`,
+      );
+    const args =
+      item.args === undefined
+        ? {}
+        : typeof item.args === "object" && !Array.isArray(item.args)
+          ? (item.args as Record<string, unknown>)
+          : undefined;
+    if (!args)
+      throw new PreviewToolError(`changes[${index}].args must be an object`);
+    return { tool: item.tool, args };
+  });
+}
+
+/** Run each change's own plan on a copy; returns the candidate score. */
+async function applyChanges(
+  changes: readonly Change[],
+  context: ToolContext,
+  action: ActionContext,
+  lookup: (name: string) => AgentTool | undefined,
+): Promise<{ score: TrackScore; summaries: string[] }> {
+  let score = context.score;
+  const summaries: string[] = [];
+  for (const change of changes) {
+    const tool = lookup(change.tool);
+    if (!tool) throw new PreviewToolError(`unknown tool ${change.tool}`);
+    let plan: ToolPlan = tool.plan(change.args, { ...context, score });
+    if (plan.kind === "prepare") plan = await plan.run(action);
+    if (plan.kind !== "score")
+      throw new PreviewToolError(`${change.tool} does not change the score`);
+    score = applyScoreOperations(score, plan.operations);
+    summaries.push(plan.summary);
+  }
+  return { score, summaries };
+}
+
+function round(stats: SoundStats) {
+  return {
+    rmsDb: Math.round(stats.rmsDb * 10) / 10,
+    peakDb: Math.round(stats.peakDb * 10) / 10,
+    centroidHz: Math.round(stats.centroidHz),
+    clipped: stats.clipped,
+    description: describeSound(stats),
+  };
+}
+
+/** One clause comparing two renders: louder/quieter, brighter/darker. */
+export function compareSounds(before: SoundStats, after: SoundStats): string {
+  const parts: string[] = [];
+  const level = after.rmsDb - before.rmsDb;
+  if (Math.abs(level) >= 0.5)
+    parts.push(
+      `${Math.abs(level).toFixed(1)} dB ${level > 0 ? "louder" : "quieter"}`,
+    );
+  if (before.centroidHz > 0 && after.centroidHz > 0) {
+    const ratio = after.centroidHz / before.centroidHz;
+    if (ratio >= 1.08) parts.push(`brighter (×${ratio.toFixed(2)} centroid)`);
+    else if (ratio <= 1 / 1.08)
+      parts.push(`darker (×${ratio.toFixed(2)} centroid)`);
+  }
+  if (after.clipped > 0 && before.clipped === 0) parts.push("now clips");
+  return parts.length ? parts.join(", ") : "about the same level and tone";
+}
+
+export function previewSoundTool(
+  lookup: (name: string) => AgentTool | undefined,
+): AgentTool {
+  return {
+    name: "preview_sound",
+    description:
+      "Hear a track, or a candidate sound change, without committing it. changes: sound tool calls to try ({tool, args} for set_fx, set_synth, set_wavetable, set_instrument, set_sample, set_effects, set_mix, set_automation, set_drum_kit, use_sound), applied to a copy. Renders the track's notes over up to 4 bars (or a short phrase by role when it has none), solo or in context, and returns RMS/peak dBFS, spectral centroid and a one-line description for the current and the candidate sound. When the user's window is open it plays the snippet once. Then commit with the normal tools if it sounds right.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: {
+          type: "string",
+          maxLength: SCORE_LIMITS.maxIdLength,
+          description: "Track to hear. Defaults to the focused track.",
+        },
+        changes: {
+          type: "array",
+          maxItems: MAX_CHANGES,
+          items: {
+            type: "object",
+            properties: {
+              tool: { type: "string", enum: [...PREVIEWABLE_TOOLS] },
+              args: { type: "object" },
+            },
+            required: ["tool"],
+          },
+        },
+        bars: { type: "integer", minimum: 1, maximum: MAX_PREVIEW_BARS },
+        context: {
+          type: "boolean",
+          description: "Hear the whole mix with the track (default: solo).",
+        },
+        play: {
+          type: "boolean",
+          description: "Play it in the user's window (default true).",
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId =
+        typeof args.trackId === "string" && args.trackId
+          ? args.trackId
+          : context.focusedTrackId;
+      const changes = parseChanges(args.changes);
+      // A candidate may create the track (set_instrument on a new id).
+      if (
+        changes.length === 0 &&
+        !context.score.tracks.some((track) => track.id === trackId)
+      )
+        throw new PreviewToolError(`unknown track ${trackId}`);
+      const bars =
+        typeof args.bars === "number" && Number.isInteger(args.bars)
+          ? Math.max(1, Math.min(MAX_PREVIEW_BARS, args.bars))
+          : undefined;
+      const inContext = args.context === true;
+      const play = args.play !== false;
+      return {
+        kind: "action",
+        summary: changes.length
+          ? `preview ${trackId} · ${changes.map((change) => change.tool).join(", ")}`
+          : `preview ${trackId}`,
+        run: async (action) => {
+          const candidate = await applyChanges(
+            changes,
+            { ...context, focusedTrackId: trackId },
+            action,
+            lookup,
+          );
+          const after = previewScore(candidate.score, trackId, {
+            context: inContext,
+          });
+          if (!after) throw new PreviewToolError(`unknown track ${trackId}`);
+          const region = bars
+            ? { startBar: after.region.startBar, bars }
+            : after.region;
+          const render =
+            action.preview?.render ?? ((value) => renderScorePcm(value));
+          const snippet = async (value: TrackScore) => {
+            const preview = previewScore(value, trackId, {
+              context: inContext,
+              region,
+            });
+            if (!preview) return undefined;
+            const audio = await render(preview.score);
+            return { audio, stats: analyzePcm(audio.pcm, audio.sampleRate) };
+          };
+          const next = await snippet(candidate.score);
+          if (!next) throw new PreviewToolError(`unknown track ${trackId}`);
+          const before =
+            changes.length > 0 &&
+            context.score.tracks.some((track) => track.id === trackId)
+              ? await snippet(context.score)
+              : undefined;
+          let played = false;
+          if (play && action.preview?.play)
+            played = await action.preview.play(next.audio);
+          const describe = describeSound(next.stats);
+          const comparison = before
+            ? compareSounds(before.stats, next.stats)
+            : undefined;
+          const content = JSON.stringify({
+            ok: true,
+            committed: false,
+            trackId,
+            bars: region.bars,
+            fromBar: region.startBar + 1,
+            source: after.source,
+            ...(after.role ? { phrase: after.role } : {}),
+            mode: inContext ? "in context" : "solo",
+            ...(candidate.summaries.length
+              ? { candidate: candidate.summaries }
+              : {}),
+            sound: round(next.stats),
+            ...(before ? { current: round(before.stats), comparison } : {}),
+            played,
+            next: changes.length
+              ? "commit with the same tool calls if it sounds right"
+              : undefined,
+          });
+          return {
+            content,
+            summary: `${played ? "♪ " : ""}preview ${trackId} · ${comparison ?? describe}`,
+          };
+        },
+      };
+    },
+  };
+}

package/src/agent/rhythm-tools.ts

@@ -0,0 +1,145 @@
+/**
+ * Agent tools for generated drum rhythms (`core/euclid.ts`, `core/rhythm.ts`).
+ *
+ * `set_rhythm` stores Euclidean/T-1 parameters on the track and lets the
+ * score regenerate the voice's notes, so the agent edits four numbers
+ * instead of sixteen notes and later edits stay one small diff.
+ */
+import { diffScores } from "../../core/diff.ts";
+import {
+  RHYTHM_LIMITS,
+  normalizeRhythmRow,
+  type RhythmRow,
+} from "../../core/euclid.ts";
+import {
+  removeRhythmRow,
+  rhythmVoicePitch,
+  setRhythmRow,
+} from "../../core/rhythm.ts";
+import { SCORE_LIMITS, ScoreValidationError } from "../../core/score.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+import { ToolArgumentError } from "./tools.ts";
+
+const int = { type: "integer" } as const;
+const num = { type: "number" } as const;
+/** Divisions are checked by `normalizeRhythmRow`; the enum stays out of the catalog. */
+const division = { type: "string" } as const;
+
+/** Compact on purpose: ranges are checked by `normalizeRhythmRow`. */
+const ROW_FIELDS = Object.freeze({
+  voice: { type: "string" },
+  pulses: int,
+  steps: int,
+  rotate: int,
+  division,
+  grid: { type: "string" },
+  repeats: int,
+  time: division,
+  pace: num,
+  ramp: num,
+  velocity: num,
+  accent: num,
+  accents: int,
+  gate: num,
+  legato: { type: "boolean" },
+  probability: num,
+  seed: int,
+  swing: num,
+  nudge: num,
+  cycles: { type: "array", items: { type: "object" } },
+});
+
+function trackOf(args: Record<string, unknown>, context: ToolContext) {
+  const trackId = args.trackId ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)
+    throw new ToolArgumentError("trackId must be a short string");
+  const track = context.score.tracks.find((t) => t.id === trackId);
+  if (!track)
+    throw new ToolArgumentError(
+      `unknown track ${trackId}; create it with create_track first`,
+    );
+  return track;
+}
+
+function rowFrom(value: unknown, label: string): RhythmRow {
+  try {
+    return normalizeRhythmRow(value, label);
+  } catch (error) {
+    throw new ToolArgumentError(
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
+
+export const RHYTHM_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "set_rhythm",
+    description:
+      "Preferred for drums: one row per voice of a kit/oneshot track; its notes regenerate from the row. pulses (4) over steps (16..64) Euclidean, rotate later; division 1/32..1/1 (1/16); grid 'x.X.' explicit (X accent); repeats 0..16 after each pulse every time, pace -1..1, ramp -1..1; velocity (0.8); accent 0..1 on E(accents,pulses); gate; legato; probability+seed; swing/nudge ±0.5 step; cycles [{pulses,rotate,repeats,probability,velocity}] per pass. remove [voices] (freeze keeps notes).",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: { type: "string" },
+        rows: {
+          type: "array",
+          maxItems: RHYTHM_LIMITS.maxRows,
+          items: {
+            type: "object",
+            properties: ROW_FIELDS,
+            required: ["voice"],
+            additionalProperties: false,
+          },
+        },
+        remove: {
+          type: "array",
+          maxItems: RHYTHM_LIMITS.maxRows,
+          items: { type: "string" },
+        },
+        freeze: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const track = trackOf(args, context);
+      const rows = Array.isArray(args.rows) ? args.rows : [];
+      const remove = Array.isArray(args.remove) ? args.remove : [];
+      if (rows.length === 0 && remove.length === 0)
+        throw new ToolArgumentError("set_rhythm needs rows or remove");
+      if (rows.length > RHYTHM_LIMITS.maxRows)
+        throw new ToolArgumentError(
+          `at most ${RHYTHM_LIMITS.maxRows} rows per call`,
+        );
+      let next = context.score;
+      const parts: string[] = [];
+      try {
+        for (const voice of remove) {
+          if (typeof voice !== "string")
+            throw new ToolArgumentError("remove holds voice names");
+          next = removeRhythmRow(next, track.id, voice, args.freeze === true);
+          parts.push(`-${voice}`);
+        }
+        for (const [index, value] of rows.entries()) {
+          const row = rowFrom(value, `rows[${index}]`);
+          if (rhythmVoicePitch(track, row.voice) === undefined)
+            throw new ToolArgumentError(
+              `track ${track.id} has no voice "${row.voice}"`,
+            );
+          next = setRhythmRow(next, track.id, row);
+          parts.push(
+            `${row.voice} ${row.grid ? `grid ${row.grid}` : `E(${row.pulses ?? 4},${row.steps ?? 16}${row.rotate ? `,${row.rotate}` : ""})`}`,
+          );
+        }
+      } catch (error) {
+        if (error instanceof ScoreValidationError)
+          throw new ToolArgumentError(error.message);
+        throw error;
+      }
+      return {
+        kind: "score",
+        operations: diffScores(context.score, next),
+        trackId: track.id,
+        summary: `${track.id} ${parts.join(", ")}`,
+      };
+    },
+  },
+]);