@hraness/dawg 0.4.0 → 0.5.0

package/src/agent/agent.ts

@@ -198,12 +198,14 @@ export const 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 calls (one add_notes call 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). Sidechain: put pads/bass on `orbit` 2 and give the kick `duck` (orbit 2, preset pump); a ducker never ducks itself.",
   "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.",
   "If a call is rejected, read the diagnostic and either fix the arguments or stop.",
   WORKSPACE_PROMPT,
   MEDIA_PROMPT,

package/src/agent/brief.ts

@@ -1,10 +1,21 @@
+import { describeMaster } from "../../core/master.ts";
 import type { TrackScore } from "../../core/score.ts";
+import {
+  describeSongTime,
+  loopTicksOf,
+  meterSegments,
+} from "../../core/tempo.ts";
 import {
   AVAILABLE_EFFECTS,
   AVAILABLE_FX_PRESETS,
   AVAILABLE_INSTRUMENTS,
 } from "../audio/wav.ts";
 import type { ProjectOutline } from "./workspace.ts";
+import {
+  describeTuning,
+  resolveTuning,
+  type Tuning,
+} from "../../core/tuning.ts";
 
 export const MAX_BRIEF_BYTES = 12 * 1024;
 const MAX_FOCUSED_NOTES = 96;
@@ -93,12 +104,35 @@ export function compositionBrief(options: {
       ...((track.delayMixAutomation?.length ?? 0) > 0
         ? { delayMixAutomation: track.delayMixAutomation!.length }
         : {}),
+      ...(track.time
+        ? {
+            // Per-track time in beats: rate, phase offset and loop cycle.
+            time: {
+              ...(track.time.rate !== undefined
+                ? { rate: track.time.rate }
+                : {}),
+              ...(track.time.phase !== undefined
+                ? { phaseBeats: beats(track.time.phase) }
+                : {}),
+              ...(track.time.cycle !== undefined
+                ? { cycleBeats: beats(track.time.cycle) }
+                : {}),
+            },
+          }
+        : {}),
+      ...(track.tuning
+        ? { tuning: tuningBrief(score.tuning, track.tuning, score.key) }
+        : {}),
       ...(track.wavetable ? { wavetable: track.wavetable } : {}),
       ...((track.wtAutomation?.length ?? 0) > 0
         ? { wtAutomation: track.wtAutomation!.length }
         : {}),
     };
   });
+  const tunedNotes = score.notes.some(
+    (note) =>
+      note.trackId === options.focusedTrackId && note.cents !== undefined,
+  );
   const focusedNotes = score.notes
     .filter((note) => note.trackId === options.focusedTrackId)
     .slice()
@@ -114,11 +148,14 @@ export function compositionBrief(options: {
       beats(note.startTick),
       beats(note.durationTicks),
       Math.round(note.velocity * 100) / 100,
+      ...(tunedNotes ? [note.cents ?? 0] : []),
     ]);
   const recent = (options.recentOperations ?? [])
     .slice(-MAX_RECENT)
     .map((line) => line.replace(/\s+/g, " ").slice(0, MAX_RECENT_CHARS));
   const project = options.project;
+  const opening = meterSegments(score)[0]!;
+  const openingMeter = `${opening.beatsPerBar}/${opening.beatUnit}`;
   const build = (
     noteLimit: number,
     trackLimit: number,
@@ -129,17 +166,30 @@ export function compositionBrief(options: {
     return JSON.stringify({
       revision: options.revision,
       tempoBpm: score.tempoBpm,
-      meter: `${score.beatsPerBar}/4`,
+      meter: openingMeter,
       bars: score.bars,
-      loopBeats: score.bars * score.beatsPerBar,
+      loopBeats: beats(loopTicksOf(score)),
+      // Tempo events (=step, →ramp; bpm@beat), meter changes and fermatas.
+      ...(score.time ? { time: describeSongTime(score) } : {}),
       ...(score.key ? { key: score.key } : {}),
+      ...(score.tuning
+        ? { tuning: tuningBrief(score.tuning, undefined, score.key) }
+        : {}),
+      ...(score.master ? { master: describeMaster(score.master) } : {}),
       focusedTrack: options.focusedTrackId,
       tracks: tracks.slice(0, trackLimit),
       ...(tracks.length > trackLimit
         ? { omittedTracks: tracks.length - trackLimit }
         : {}),
       focusedNotes: {
-        columns: ["id", "pitch", "startBeat", "durationBeats", "velocity"],
+        columns: [
+          "id",
+          "pitch",
+          "startBeat",
+          "durationBeats",
+          "velocity",
+          ...(tunedNotes ? ["cents"] : []),
+        ],
         rows: visible,
         ...(focusedNotes.length > visible.length
           ? { omitted: focusedNotes.length - visible.length }
@@ -183,3 +233,27 @@ export function compositionBrief(options: {
 export function noteName(midi: number): string {
   return `${NOTE_NAMES[midi % 12]}${Math.floor(midi / 12) - 1}`;
 }
+
+/**
+ * A tuning as the agent reads it: the summary, plus the steps per period and
+ * whether keys map one per step (`linear`), in which case a key name such as
+ * C5 no longer sounds as its 12-TET pitch.
+ */
+function tuningBrief(
+  song: Tuning | undefined,
+  track: Tuning | undefined,
+  key: string | null | undefined,
+): { summary: string; steps?: number; linear?: boolean } {
+  const summary = describeTuning(track ?? song);
+  try {
+    const table = resolveTuning(song, track, key);
+    if (!table) return { summary };
+    return {
+      summary,
+      steps: table.size,
+      ...(table.linear && table.size !== 12 ? { linear: true } : {}),
+    };
+  } catch {
+    return { summary };
+  }
+}

package/src/agent/chord-tools.ts

@@ -24,6 +24,7 @@ import {
   type Spread,
 } from "../../core/chords.ts";
 import { midiToPitch } from "../../core/pitch.ts";
+import { resolveTuning, snapToTuning } from "../../core/tuning.ts";
 import { SCORE_LIMITS, type ScoreOperation } from "../../core/score.ts";
 import type { AgentTool, ToolContext } from "./tools.ts";
 
@@ -266,6 +267,12 @@ export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
           `${total} notes exceed ${MAX_CHORD_NOTES}; use fewer chords, a slower rate or fewer octaves`,
         );
       const tpb = context.score.ticksPerBeat;
+      const tuningOf = (id: string) =>
+        resolveTuning(
+          context.score.tuning,
+          context.score.tracks.find((track) => track.id === id)?.tuning,
+          context.score.key,
+        );
       const operations: ScoreOperation[] = [];
       const add = (
         notes: readonly {
@@ -276,6 +283,7 @@ export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
         }[],
         target: string,
       ) => {
+        const table = tuningOf(target);
         for (const note of notes)
           operations.push({
             type: "addNote",
@@ -284,7 +292,7 @@ export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
               trackId: target,
               startTick: Math.round(note.start * tpb),
               durationTicks: Math.max(1, Math.round(note.length * tpb)),
-              pitch: note.pitch,
+              pitch: snapToTuning(note.pitch, table),
               velocity: note.velocity,
             },
           });

package/src/agent/expression-tools.ts

@@ -0,0 +1,336 @@
+/**
+ * Agent tools for expression: `set_expression` (articulation, glide, bend
+ * and vibrato over a note range) and `set_performance` (a track's glide
+ * mode, sustain pedal, velocity curve and seeded humanize). Both validate
+ * through core/expression.ts, the same rules the score loader applies.
+ */
+import {
+  ARTICULATIONS,
+  ExpressionValidationError,
+  GLIDE_MODES,
+  PEDAL_STATES,
+  VELOCITY_CURVES,
+  normalizeArticulation,
+  normalizeBend,
+  normalizeHumanize,
+  normalizeNoteGlide,
+  normalizePedal,
+  normalizeTrackGlide,
+  normalizeVelocityCurve,
+  normalizeVibrato,
+  normalizeNoteHumanize,
+  type NoteExpressionPatch,
+} from "../../core/expression.ts";
+import {
+  SCORE_LIMITS,
+  type ScoreOperation,
+  type TrackPatch,
+} from "../../core/score.ts";
+import { loopTicksOf } from "../../core/tempo.ts";
+import { BEND_SHAPES, barPedal } from "../commands/expression.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+
+const MAX_TARGET_NOTES = 512;
+
+class ExpressionToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+function validated<T>(read: () => T): T {
+  try {
+    return read();
+  } catch (error) {
+    if (error instanceof ExpressionValidationError)
+      throw new ExpressionToolError(error.message);
+    throw error;
+  }
+}
+
+function trackOf(args: Record<string, unknown>, context: ToolContext): string {
+  const trackId = args.trackId ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)
+    throw new ExpressionToolError("trackId must be a short string");
+  if (!context.score.tracks.some((track) => track.id === trackId))
+    throw new ExpressionToolError(`unknown trackId ${trackId.slice(0, 64)}`);
+  return trackId;
+}
+
+function beat(args: Record<string, unknown>, key: string): number | undefined {
+  const value = args[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+    throw new ExpressionToolError(`${key} must be a number >= 0`);
+  return value;
+}
+
+/** Note ids `args` selects: `noteIds`, else the track's notes in a beat range. */
+function selectNotes(
+  args: Record<string, unknown>,
+  context: ToolContext,
+): { trackId: string; noteIds: string[] } {
+  const trackId = trackOf(args, context);
+  if (args.noteIds !== undefined) {
+    if (
+      !Array.isArray(args.noteIds) ||
+      args.noteIds.length === 0 ||
+      args.noteIds.length > MAX_TARGET_NOTES
+    )
+      throw new ExpressionToolError(
+        `noteIds must be an array of 1..${MAX_TARGET_NOTES} ids`,
+      );
+    const known = new Set(context.score.notes.map((note) => note.id));
+    const ids = [...new Set(args.noteIds as unknown[])].map((id, index) => {
+      if (typeof id !== "string" || !known.has(id))
+        throw new ExpressionToolError(`noteIds[${index}] is not a note id`);
+      return id;
+    });
+    return { trackId, noteIds: ids };
+  }
+  const tpb = context.score.ticksPerBeat;
+  const from = beat(args, "fromBeat") ?? 0;
+  const to = beat(args, "toBeat") ?? Infinity;
+  if (!(to > from))
+    throw new ExpressionToolError("toBeat must be after fromBeat");
+  const noteIds = context.score.notes
+    .filter(
+      (note) =>
+        note.trackId === trackId &&
+        note.startTick >= Math.round(from * tpb) &&
+        note.startTick < to * tpb,
+    )
+    .map((note) => note.id);
+  if (noteIds.length === 0)
+    throw new ExpressionToolError(
+      `no notes on ${trackId} start in beats ${from}..${to === Infinity ? "end" : to}`,
+    );
+  if (noteIds.length > MAX_TARGET_NOTES)
+    throw new ExpressionToolError(
+      `${noteIds.length} notes match; narrow the range to ${MAX_TARGET_NOTES}`,
+    );
+  return { trackId, noteIds };
+}
+
+const noteRange = {
+  trackId: { type: "string" },
+  noteIds: { type: "array", items: { type: "string" } },
+  fromBeat: { type: "number" },
+  toBeat: { type: "number" },
+};
+
+const bendPoint = {
+  type: "object",
+  properties: { at: { type: "number" }, cents: { type: "number" } },
+};
+
+export const EXPRESSION_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "set_expression",
+    description: `Per-note expression on noteIds, or on trackId's notes starting in [fromBeat, toBeat); null clears. articulation: staccato halves length, legato holds to the next note, accent/marcato louder, ghost quiet. glide: seconds sliding in from the previous pitch. bend: [{at 0..1, cents}] or ${Object.keys(BEND_SHAPES).join("|")}. vibrato: {rate Hz, depth cents, delay s}. humanize: {timing ms, velocity %, length %} for just these notes, replacing the track's amounts ({} keeps them exact). Overrides the synth's slide, penv, vib. On a legato-glide track a note glides when it overlaps the previous one (use articulation legato), or, with its own glide, when the previous note ends at most a 16th step earlier (a TB-303 slide; a longer rest never slides).`,
+    parameters: {
+      type: "object",
+      properties: {
+        ...noteRange,
+        articulation: {
+          type: ["string", "null"],
+          enum: [...ARTICULATIONS, null],
+        },
+        glide: { type: ["number", "null"] },
+        bend: { type: ["array", "string", "null"], items: bendPoint },
+        vibrato: {
+          type: ["object", "null"],
+          properties: {
+            rate: { type: "number" },
+            depth: { type: "number" },
+            delay: { type: "number" },
+          },
+        },
+        humanize: {
+          type: ["object", "null"],
+          properties: {
+            timing: { type: "number" },
+            velocity: { type: "number" },
+            length: { type: "number" },
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const patch: Record<string, unknown> = {};
+      if (args.articulation !== undefined)
+        patch.articulation =
+          args.articulation === null
+            ? null
+            : validated(() => normalizeArticulation(args.articulation));
+      if (args.glide !== undefined)
+        patch.glide =
+          args.glide === null
+            ? null
+            : validated(() => normalizeNoteGlide(args.glide));
+      if (args.bend !== undefined)
+        patch.bend =
+          args.bend === null
+            ? null
+            : typeof args.bend === "string"
+              ? (BEND_SHAPES[args.bend] ??
+                (() => {
+                  throw new ExpressionToolError(
+                    `bend shape must be one of ${Object.keys(BEND_SHAPES).join(", ")}`,
+                  );
+                })())
+              : (validated(() => normalizeBend(args.bend)) ?? null);
+      if (args.vibrato !== undefined)
+        patch.vibrato =
+          args.vibrato === null
+            ? null
+            : validated(() => normalizeVibrato(args.vibrato));
+      if (args.humanize !== undefined)
+        patch.humanize =
+          args.humanize === null
+            ? null
+            : validated(() => normalizeNoteHumanize(args.humanize));
+      if (Object.keys(patch).length === 0)
+        throw new ExpressionToolError(
+          "set at least one of articulation, glide, bend, vibrato, humanize",
+        );
+      const { trackId, noteIds } = selectNotes(args, context);
+      const operations: ScoreOperation[] = noteIds.map((noteId) => ({
+        type: "updateNote",
+        noteId,
+        patch: patch as NoteExpressionPatch,
+      }));
+      const fields = Object.entries(patch)
+        .map(([key, value]) =>
+          value === null
+            ? `${key} off`
+            : typeof value === "string" || typeof value === "number"
+              ? `${key} ${value}`
+              : key,
+        )
+        .join(", ");
+      return {
+        kind: "score",
+        operations,
+        trackId,
+        summary: `${fields} · ${noteIds.length} note${noteIds.length === 1 ? "" : "s"}`,
+      };
+    },
+  },
+  {
+    name: "set_performance",
+    description:
+      'A track\'s performance; null clears. glide: {time s, mode legato|mono|poly}: legato slides only between overlapping notes without retriggering (TB-303), mono always slides, poly slides every voice. pedal: [{beat, state down|half|up}] or "bars" to re-pedal each bar. velocityCurve: {curve linear|soft|hard|fixed, fixed 0..1}. humanize: {timing ms, velocity %, length %, seed} applied at render; keep the seed for the same take.',
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: { type: "string" },
+        glide: {
+          type: ["object", "null"],
+          properties: {
+            time: { type: "number" },
+            mode: { type: "string", enum: GLIDE_MODES },
+          },
+        },
+        pedal: {
+          type: ["array", "string", "null"],
+          items: {
+            type: "object",
+            properties: {
+              beat: { type: "number" },
+              state: { type: "string", enum: PEDAL_STATES },
+            },
+          },
+        },
+        velocityCurve: {
+          type: ["object", "null"],
+          properties: {
+            curve: { type: "string", enum: VELOCITY_CURVES },
+            fixed: { type: "number" },
+          },
+        },
+        humanize: {
+          type: ["object", "null"],
+          properties: {
+            timing: { type: "number" },
+            velocity: { type: "number" },
+            length: { type: "number" },
+            seed: { type: "integer" },
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = trackOf(args, context);
+      const track = context.score.tracks.find((item) => item.id === trackId)!;
+      const score = context.score;
+      const patch: Record<string, unknown> = {};
+      if (args.glide !== undefined)
+        patch.glide =
+          args.glide === null
+            ? null
+            : validated(() =>
+                normalizeTrackGlide({
+                  ...(track.glide ?? {}),
+                  ...(args.glide as Record<string, unknown>),
+                }),
+              );
+      if (args.pedal !== undefined) {
+        const maxTick = loopTicksOf(score);
+        if (args.pedal === null) patch.pedal = null;
+        else if (args.pedal === "bars") patch.pedal = barPedal(score);
+        else {
+          if (!Array.isArray(args.pedal))
+            throw new ExpressionToolError(
+              'pedal must be an array, "bars" or null',
+            );
+          const events = args.pedal.map((value: unknown, index) => {
+            const event = value as Record<string, unknown>;
+            const at = beat(event ?? {}, "beat");
+            if (at === undefined)
+              throw new ExpressionToolError(`pedal[${index}].beat is required`);
+            return {
+              tick: Math.round(at * score.ticksPerBeat),
+              state: event.state,
+            };
+          });
+          patch.pedal =
+            validated(() => normalizePedal(events, maxTick)) ?? null;
+        }
+      }
+      if (args.velocityCurve !== undefined)
+        patch.velocityCurve =
+          args.velocityCurve === null
+            ? null
+            : (validated(() => normalizeVelocityCurve(args.velocityCurve)) ??
+              null);
+      if (args.humanize !== undefined)
+        patch.humanize =
+          args.humanize === null
+            ? null
+            : (validated(() =>
+                normalizeHumanize({
+                  ...(track.humanize ?? { seed: 1 }),
+                  ...(args.humanize as Record<string, unknown>),
+                }),
+              ) ?? null);
+      if (Object.keys(patch).length === 0)
+        throw new ExpressionToolError(
+          "set at least one of glide, pedal, velocityCurve, humanize",
+        );
+      return {
+        kind: "score",
+        operations: [
+          { type: "updateTrack", trackId, patch: patch as TrackPatch },
+        ],
+        trackId,
+        summary: `${trackId} ${Object.entries(patch)
+          .map(([key, value]) => (value === null ? `${key} off` : key))
+          .join(", ")}`,
+      };
+    },
+  },
+] satisfies AgentTool[]);