@hraness/dawg 0.3.0 → 0.4.0

package/src/agent/tools.ts

@@ -1,13 +1,50 @@
 import {
-  AUTOMATION_LANES,
+  AUTOMATION_PARAMETERS,
+  automationPoints,
+  automationRange,
   SCORE_LIMITS,
   type AutomationParameter,
   type ScoreOperation,
   type TrackScore,
 } from "../../core/score.ts";
 import { AVAILABLE_INSTRUMENTS } from "../audio/wav.ts";
+import {
+  SYNTH_PRESETS,
+  SYNTH_SIMPLE,
+  isSynthPreset,
+  synthParamName,
+} from "../../core/synth.ts";
+import { applySynthCommand, type SynthCommand } from "../commands/synth.ts";
+import {
+  setSampleControls,
+  type SampleControlValue,
+} from "../commands/sample.ts";
+import {
+  EFFECT_NAMES,
+  FX_PRESETS,
+  effectSpec,
+  type EffectName,
+} from "../../core/fx.ts";
+import {
+  applyFxCommand,
+  effectPatch,
+  effectValues,
+  parseEffectName,
+  parseParamName,
+  type FxCommand,
+} from "../commands/fx.ts";
 import type { ChatTool } from "./gateway.ts";
 import { MEDIA_TOOLS } from "../media/tools.ts";
+import { PACK_TOOLS, PackToolError } from "./pack-tools.ts";
+import {
+  PreviewToolError,
+  previewSoundTool,
+  type PreviewHost,
+} from "./preview-tool.ts";
+import { PackError, type PackStore } from "../audio/packs.ts";
+import { RHYTHM_TOOLS } from "./rhythm-tools.ts";
+import { CHORD_TOOLS } from "./chord-tools.ts";
+import { DRUM_TOOLS } from "./drum-tools.ts";
 import type { MediaResult, MediaRunContext } from "../media/types.ts";
 import { pitchToMidi } from "./ops.ts";
 import {
@@ -43,6 +80,13 @@ import {
 } from "../web/search.ts";
 
 /** What a validated tool call asks the host to do. */
+export type ScorePlan = Readonly<{
+  kind: "score";
+  operations: readonly ScoreOperation[];
+  summary: string;
+  trackId?: string;
+}>;
+
 export type ToolPlan =
   | Readonly<{
       kind: "score";
@@ -62,6 +106,15 @@ export type ToolPlan =
       /** Side effects outside the score (files, network); bounded and async. */
       run: (context: ActionContext) => Promise<ActionResult>;
     }>
+  /**
+   * Score edits that need async work first (fetching a pack sound); `run`
+   * returns the score plan, committed like any other.
+   */
+  | Readonly<{
+      kind: "prepare";
+      summary: string;
+      run: (context: ActionContext) => Promise<ScorePlan>;
+    }>
   /** A long-running local media job (download, stems, analysis, …). */
   | Readonly<{
       kind: "media";
@@ -105,6 +158,10 @@ export type ActionContext = Readonly<{
   onWorkspaceWrite?: (path: string) => Promise<string | void> | string | void;
   web?: WebHost;
   signal?: AbortSignal;
+  /** Sample packs for list_packs/search_sounds/use_sound; default the user cache. */
+  packs?: PackStore;
+  /** Render and play hooks for preview_sound; absent renders in-thread, silent. */
+  preview?: PreviewHost;
 }>;
 
 export type ActionResult = Readonly<{
@@ -139,10 +196,6 @@ export class ToolArgumentError extends Error {
   }
 }
 
-const AUTOMATION_PARAMETERS = Object.keys(
-  AUTOMATION_LANES,
-) as AutomationParameter[];
-
 const MAX_NOTES_PER_CALL = 128;
 const MAX_EXPLAIN_CHARS = 2_000;
 const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
@@ -422,12 +475,16 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     name: "set_automation",
-    description: `Write an automation lane: volume (0..1), pan (-1..1), filter cutoff (${SCORE_LIMITS.minFilterCutoff}..${SCORE_LIMITS.maxFilterCutoff} Hz low-pass), resonance (0..${SCORE_LIMITS.maxFilterResonance}), delay-feedback (0..${SCORE_LIMITS.maxDelayFeedback}) or delay-mix (0..${SCORE_LIMITS.maxDelayMix}). Delay lanes need a delay on the track (set_effects) to be heard. mode=replace (default) rewrites the lane; merge keeps existing points at other beats. An empty replace clears it.`,
+    description: `Write an automation lane: volume 0..1, pan -1..1, filter (cutoff Hz), resonance 0..${SCORE_LIMITS.maxFilterResonance}, delay-feedback 0..${SCORE_LIMITS.maxDelayFeedback}, delay-mix, wt (wavetable position 0..1), or <effect>-<param> (the param's range). The effect must be on to be heard. mode=replace (default) rewrites the lane; merge keeps other beats. An empty replace clears it.`,
     parameters: {
       type: "object",
       properties: {
         trackId: trackIdSchema,
-        parameter: { type: "string", enum: AUTOMATION_PARAMETERS },
+        parameter: {
+          type: "string",
+          description:
+            "volume, pan, filter, resonance, delay-feedback, delay-mix, or <effect>-<param>",
+        },
         mode: { type: "string", enum: ["replace", "merge"] },
         points: {
           type: "array",
@@ -438,8 +495,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
               beat: beatSchema("Beat position"),
               value: {
                 type: "number",
-                description:
-                  "volume 0..1, pan -1..1, filter cutoff in Hz, resonance 0..1, delay-feedback 0..0.9, delay-mix 0..1",
+                description: "in the lane's range",
               },
             },
             required: ["beat", "value"],
@@ -461,7 +517,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         args.mode === undefined
           ? "replace"
           : oneOf(args.mode, ["replace", "merge"], "mode");
-      const { min, max } = AUTOMATION_LANES[parameter];
+      const { min, max } = automationRange(parameter);
       const tpb = context.score.ticksPerBeat;
       const points = list(
         args,
@@ -476,7 +532,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         };
       });
       const track = context.score.tracks.find((t) => t.id === trackId)!;
-      const existing = track[AUTOMATION_LANES[parameter].field] ?? [];
+      const existing = automationPoints(track, parameter);
       const merged = Array.from(
         new Map(
           [...(mode === "merge" ? existing : []), ...points].map((point) => [
@@ -498,9 +554,153 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    name: "set_fx",
+    description:
+      "Turn an effect on/off, load a preset, or set params by dawg or Strudel name (lpq, delayfeedback…). on:true uses good defaults; effects and presets are in the brief.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        effect: { type: "string", description: "see the brief's effects" },
+        on: { type: "boolean" },
+        preset: { type: "string" },
+        params: {
+          type: "object",
+          additionalProperties: { type: ["number", "string", "boolean"] },
+        },
+      },
+      required: ["effect"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const effect =
+        typeof args.effect === "string"
+          ? parseEffectName(args.effect)
+          : undefined;
+      if (!effect)
+        throw new ToolArgumentError(
+          `effect must be one of ${EFFECT_NAMES.join(", ")}`,
+        );
+      const command = fxToolCommand(effect, args);
+      const result = applyFxCommand(context.score, trackId, command);
+      if (!result.ok || !result.next)
+        throw new ToolArgumentError(result.message);
+      const track = context.score.tracks.find((t) => t.id === trackId)!;
+      const values = effectValues(
+        result.next.tracks.find((t) => t.id === trackId),
+        effect,
+      );
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: effectPatch(track, effect, values ?? null),
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${result.message}`,
+      };
+    },
+  },
+  {
+    name: "set_synth",
+    description:
+      "Shape a synth track's voice with Strudel synth params (attack decay sustain release, lpf lpq lpenv, fm fmh, unison detune spread, vib vibmod, penv, noise, pw…); null unsets one. preset loads a voice (instrument + params); reset clears all; zzfx takes a raw ZzFX array (empty slots null) and sets a z_* sound.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        preset: { type: "string", enum: Object.keys(SYNTH_PRESETS) },
+        reset: { type: "boolean" },
+        zzfx: {
+          type: "array",
+          maxItems: 21,
+          items: { type: ["number", "null"] },
+        },
+        params: {
+          type: "object",
+          additionalProperties: {
+            type: ["number", "string", "boolean", "array", "null"],
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const command = synthToolCommand(args);
+      const result = applySynthCommand(context.score, trackId, command);
+      if (!result.ok || !result.next)
+        throw new ToolArgumentError(result.message);
+      const next = result.next.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: { instrument: next.instrument, synth: next.synth ?? null },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${result.message}`,
+      };
+    },
+  },
+  {
+    name: "set_sample",
+    description:
+      "Set a sampler voice's Strudel sample controls: begin end gain speed unit(r|c|s) loop loopBegin loopEnd clip(legato) fit loopAt accelerate squiz cut; null unsets one.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        voice: { type: "string" },
+        params: {
+          type: "object",
+          additionalProperties: {
+            type: ["number", "string", "boolean", "null"],
+          },
+        },
+      },
+      required: ["voice", "params"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const params = args.params;
+      if (
+        typeof args.voice !== "string" ||
+        typeof params !== "object" ||
+        params === null ||
+        Array.isArray(params)
+      )
+        throw new ToolArgumentError("set_sample needs voice and params");
+      const result = setSampleControls(
+        context.score,
+        trackId,
+        args.voice,
+        params as Record<string, SampleControlValue>,
+      );
+      if (!result.ok) throw new ToolArgumentError(result.message);
+      const next = result.next.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          { type: "updateTrack", trackId, patch: { sampler: next.sampler } },
+        ],
+        trackId,
+        summary: `${trackId} ${result.message}`,
+      };
+    },
+  },
   {
     name: "set_effects",
-    description: `Set or remove a track's low-pass filter, tempo-synced stereo delay, and stereo reverb send. Pass null to remove an effect. filter: cutoff ${SCORE_LIMITS.minFilterCutoff}..${SCORE_LIMITS.maxFilterCutoff} Hz, resonance 0..${SCORE_LIMITS.maxFilterResonance}. delay: beats ${SCORE_LIMITS.minDelayBeats}..${SCORE_LIMITS.maxDelayBeats}, feedback 0..${SCORE_LIMITS.maxDelayFeedback}, mix 0..${SCORE_LIMITS.maxDelayMix}. reverb: mix 0..${SCORE_LIMITS.maxReverbMix} (0.15..0.35 is a natural room), size ${SCORE_LIMITS.minReverbSize}..${SCORE_LIMITS.maxReverbSize} (default 0.5; higher is a longer, darker tail).`,
+    description: `Shorthand: low-pass filter, delay (beats) and reverb (mix 0.15..0.35 is a room); null removes one. Prefer set_fx.`,
     parameters: {
       type: "object",
       properties: {
@@ -660,7 +860,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     name: "add_drums",
-    description: `Add drum hits to a kit track (create one with create_track instrument "kit"). Voices: ${DRUM_VOICES.map((info) => info.voice).join(", ")}. Give explicit hits, and/or patterns that repeat a voice every N beats across the loop.`,
+    description: `Add one-off drum hits to a kit track (create one with create_track instrument "kit"); prefer set_rhythm for repeating beats. Voices: ${DRUM_VOICES.map((info) => info.voice).join(", ")}. Give explicit hits, and/or patterns that repeat a voice every N beats across the loop.`,
     parameters: {
       type: "object",
       properties: {
@@ -1148,7 +1348,13 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  ...RHYTHM_TOOLS,
+  ...CHORD_TOOLS,
+  ...DRUM_TOOLS,
   ...MEDIA_TOOLS,
+  ...PACK_TOOLS,
+  // Looks tools up at call time, so it can plan any of the above.
+  previewSoundTool((name) => findAgentTool(name)),
 ] satisfies AgentTool[]);
 
 /** Errors an `action` plan may raise that are safe to show to the model. */
@@ -1156,7 +1362,10 @@ export function isActionDiagnostic(error: unknown): boolean {
   return (
     error instanceof WorkspaceError ||
     error instanceof WebError ||
-    error instanceof ToolArgumentError
+    error instanceof ToolArgumentError ||
+    error instanceof PackToolError ||
+    error instanceof PreviewToolError ||
+    error instanceof PackError
   );
 }
 
@@ -1250,6 +1459,91 @@ export function chatTools(
   }));
 }
 
+function fxToolCommand(
+  effect: EffectName,
+  args: Record<string, unknown>,
+): FxCommand {
+  if (args.on === false) return { type: "fx-off", effect };
+  if (args.preset !== undefined) {
+    if (
+      typeof args.preset !== "string" ||
+      !Object.prototype.hasOwnProperty.call(
+        FX_PRESETS[effect] ?? {},
+        args.preset,
+      )
+    )
+      throw new ToolArgumentError(
+        `${effect} presets: ${Object.keys(FX_PRESETS[effect] ?? {}).join(", ") || "none"}`,
+      );
+    return { type: "fx-preset", effect, preset: args.preset };
+  }
+  if (args.params === undefined) {
+    if (args.on === true) return { type: "fx-on", effect };
+    throw new ToolArgumentError("set_fx needs on, preset, or params");
+  }
+  const params = record(args.params, "params");
+  const values: Record<string, number | string | boolean> = {};
+  for (const [name, value] of Object.entries(params)) {
+    const param = parseParamName(effect, name);
+    if (!param)
+      throw new ToolArgumentError(
+        `${effect} has no parameter ${name}; it takes ${Object.keys(effectSpec(effect).params).join(", ")}`,
+      );
+    if (
+      typeof value !== "number" &&
+      typeof value !== "string" &&
+      typeof value !== "boolean"
+    )
+      throw new ToolArgumentError(`${effect} ${name} must be a value`);
+    values[param] = value;
+  }
+  return { type: "fx-set", effect, values };
+}
+
+function synthToolCommand(args: Record<string, unknown>): SynthCommand {
+  if (args.reset === true) return { type: "synth-reset" };
+  if (args.zzfx !== undefined) {
+    if (
+      !Array.isArray(args.zzfx) ||
+      args.zzfx.length > 21 ||
+      !args.zzfx.every((n) => n === null || typeof n === "number")
+    )
+      throw new ToolArgumentError("zzfx must be up to 21 numbers or nulls");
+    return { type: "synth-zzfx", values: args.zzfx as (number | null)[] };
+  }
+  if (args.preset !== undefined) {
+    if (typeof args.preset !== "string" || !isSynthPreset(args.preset))
+      throw new ToolArgumentError(
+        `synth presets: ${Object.keys(SYNTH_PRESETS).join(", ")}`,
+      );
+    return { type: "synth-preset", preset: args.preset };
+  }
+  if (args.params === undefined)
+    throw new ToolArgumentError("set_synth needs preset, reset, or params");
+  const params = record(args.params, "params");
+  const values: Record<
+    string,
+    number | string | boolean | readonly number[] | null
+  > = {};
+  for (const [name, value] of Object.entries(params)) {
+    const param = synthParamName(name);
+    if (!param)
+      throw new ToolArgumentError(
+        `synth has no parameter ${name}; basics: ${SYNTH_SIMPLE.join(", ")} (DAWG.md lists all)`,
+      );
+    if (
+      value !== null &&
+      typeof value !== "number" &&
+      typeof value !== "string" &&
+      typeof value !== "boolean" &&
+      !(Array.isArray(value) && value.every((n) => typeof n === "number"))
+    )
+      throw new ToolArgumentError(`synth ${name} must be a value`);
+    values[param] = value as number;
+  }
+  return { type: "synth-set", values };
+}
+
 function targetTrack(args: Record<string, unknown>, context: ToolContext) {
   const trackId = args.trackId ?? context.focusedTrackId;
   if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)

package/src/agent/xcb-agent.ts

@@ -1,4 +1,5 @@
 import { compositionBrief } from "./brief.ts";
+import { CHORD_PROCESS } from "../../core/chords.ts";
 import {
   AGENT_LIMITS,
   MEDIA_PROMPT,
@@ -44,8 +45,13 @@ export const TEXT_AGENT_SYSTEM_PROMPT = [
   "You edit the score by returning operations. Each op is validated and applied immediately, in order, as its own revision.",
   "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 use add_drums; drum pitches select voices, so do not use add_notes for beats.',
-  "Effects (set_effects, set_automation): low-pass filter cutoff 20..20000 Hz and resonance 0..1; stereo delay beats 0.0625..4, feedback 0..0.9, mix 0..1; stereo reverb mix 0..1 (0.15..0.35 is a natural room) and size 0..1; pan -1..1 is equal-power stereo. Automatable lanes: volume, pan, filter, resonance, delay-feedback, delay-mix.",
+  '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.',
+  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.",
   '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.",

package/src/audio/audition.ts

@@ -0,0 +1,93 @@
+/**
+ * Audition: a short phrase of one track (or some of its pitches) rendered
+ * through the offline renderer, as a live voice the engine can mix over
+ * silence. The Euclidean editor plays the edited voice's lane once after
+ * every change, and the pattern picker previews a pattern before it lands.
+ *
+ * Like `live.ts` this only builds a smaller score; the renderer is shared,
+ * so an audition sounds exactly like the loop.
+ */
+import {
+  SCORE_LIMITS,
+  TrackScore,
+  type Note,
+  type Track,
+} from "../../core/score.ts";
+import type { LiveNotePcm } from "./live.ts";
+import type { SampleBank } from "./samples.ts";
+import { RENDER_CHANNELS, renderScorePcm } from "./wav.ts";
+
+export type AuditionRequest = Readonly<{
+  score: TrackScore;
+  trackId: string;
+  /** Only these pitches (one drum voice); all of the track's notes when absent. */
+  pitches?: ReadonlySet<number>;
+  /** Bars rendered from the loop start (default 1, at most the loop). */
+  bars?: number;
+  sampleRate: number;
+  samples?: SampleBank;
+}>;
+
+/** Longest audition, so a slow tempo cannot hold a voice for long. */
+export const MAX_AUDITION_SECONDS = 6;
+
+export function renderAudition(
+  request: AuditionRequest,
+): LiveNotePcm | undefined {
+  const { score } = request;
+  const track = score.tracks.find(
+    (candidate) => candidate.id === request.trackId,
+  );
+  if (!track) return undefined;
+  const secondsPerBar = (score.beatsPerBar * 60) / score.tempoBpm;
+  const bars = Math.max(
+    1,
+    Math.min(
+      score.bars,
+      request.bars ?? 1,
+      Math.floor(MAX_AUDITION_SECONDS / secondsPerBar) || 1,
+    ),
+  );
+  const endTick = bars * score.beatsPerBar * score.ticksPerBeat;
+  const notes: Note[] = score.notes.filter(
+    (note) =>
+      note.trackId === track.id &&
+      note.startTick < endTick &&
+      (!request.pitches || request.pitches.has(note.pitch)),
+  );
+  if (notes.length === 0) return undefined;
+  const single = new TrackScore({
+    tempoBpm: score.tempoBpm,
+    beatsPerBar: score.beatsPerBar,
+    bars,
+    ticksPerBeat: score.ticksPerBeat,
+    tracks: [auditionTrack(track)],
+    notes: notes.map((note) => ({
+      ...note,
+      durationTicks: Math.max(
+        1,
+        Math.min(
+          note.durationTicks,
+          endTick - note.startTick,
+          SCORE_LIMITS.maxTick,
+        ),
+      ),
+    })),
+  });
+  const audio = renderScorePcm(single, {
+    sampleRate: request.sampleRate,
+    maxSeconds: MAX_AUDITION_SECONDS + 4,
+    ...(request.samples ? { samples: request.samples } : {}),
+  });
+  let last = audio.pcm.length - 1;
+  while (last >= 0 && audio.pcm[last] === 0) last -= 1;
+  const frames = Math.ceil((last + 1) / RENDER_CHANNELS);
+  if (frames === 0) return undefined;
+  return { pcm: audio.pcm.subarray(0, frames * RENDER_CHANNELS), frames };
+}
+
+/** Audible regardless of mute and solo; the generator rows are not needed. */
+function auditionTrack(track: Track): Track {
+  const { solo: _solo, rhythm: _rhythm, ...rest } = track;
+  return { ...rest, muted: false };
+}