@hraness/dawg 0.4.0 → 0.5.0

package/src/agent/master-tools.ts

@@ -0,0 +1,299 @@
+/**
+ * Agent tools for the song master: `set_master` (score) edits the chain and
+ * loudness target through the same `nextMaster` path as the `master` prompt
+ * command, and `measure_mix` (read-only) renders the song and reports
+ * loudness (BS.1770 / EBU R 128), true peak, spectral balance and stereo
+ * correlation, so the agent can check a mix before and after mastering.
+ */
+
+import {
+  LOUDNESS_TARGET_NAMES,
+  LOUDNESS_TARGETS,
+  MASTER_LIMITS,
+  MASTER_PRESETS,
+  MASTER_SPECS,
+  MASTER_UNITS,
+  describeMaster,
+  isLoudnessTargetName,
+  isMasterUnit,
+  normalizeMaster,
+  type MasterUnit,
+  type SongMaster,
+} from "../../core/master.ts";
+import { FxValidationError } from "../../core/params.ts";
+import { ScoreValidationError, type TrackScore } from "../../core/score.ts";
+import {
+  exportSampleRate,
+  measureScore,
+  type ScoreMeasurement,
+} from "../audio/measure.ts";
+import { nextMaster, type MasterCommand } from "../commands/master.ts";
+import type { AgentTool } from "./tools.ts";
+import type { PreviewHost } from "./preview-tool.ts";
+
+class MasterToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+const TARGET_LIST = LOUDNESS_TARGET_NAMES.map(
+  (name) => `${name} ${LOUDNESS_TARGETS[name].lufs}`,
+).join(", ");
+
+const UNIT_ARGS = Object.fromEntries(
+  MASTER_UNITS.map((unit) => [
+    unit,
+    {
+      description: `${MASTER_SPECS[unit].doc}; params ${Object.keys(MASTER_SPECS[unit].params).join(" ")}`,
+      anyOf: [
+        { type: "boolean" },
+        { type: "string", enum: Object.keys(MASTER_PRESETS[unit]) },
+        { type: "object" },
+      ],
+    },
+  ]),
+);
+
+function unitCommands(unit: MasterUnit, value: unknown): MasterCommand[] {
+  if (value === undefined) return [];
+  if (value === true || value === false)
+    return [{ type: "master-unit", unit, on: value }];
+  if (typeof value === "string") {
+    if (!Object.hasOwn(MASTER_PRESETS[unit], value))
+      throw new MasterToolError(
+        `${unit} preset must be one of ${Object.keys(MASTER_PRESETS[unit]).join(", ")}`,
+      );
+    return [{ type: "master-preset", unit, preset: value }];
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new MasterToolError(
+      `${unit} must be true, false, a preset name or params`,
+    );
+  const values: Record<string, number | string | boolean> = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (
+      typeof raw !== "number" &&
+      typeof raw !== "string" &&
+      typeof raw !== "boolean"
+    )
+      throw new MasterToolError(`${unit}.${key} must be a number or string`);
+    values[key] = raw;
+  }
+  return [{ type: "master-set", unit, values }];
+}
+
+function targetCommand(value: unknown): MasterCommand | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || value === "off")
+    return { type: "master-target", lufs: null };
+  if (typeof value === "string") {
+    if (!isLoudnessTargetName(value))
+      throw new MasterToolError(
+        `target must be LUFS or one of ${LOUDNESS_TARGET_NAMES.join(", ")}`,
+      );
+    return {
+      type: "master-target",
+      lufs: LOUDNESS_TARGETS[value].lufs,
+      name: value,
+    };
+  }
+  if (typeof value !== "number" || !Number.isFinite(value))
+    throw new MasterToolError("target must be LUFS, a name or null");
+  // Like the prompt's `master target 14`: loudness targets are negative.
+  return { type: "master-target", lufs: -Math.abs(value) };
+}
+
+function round(value: number, digits = 1): number | null {
+  if (!Number.isFinite(value)) return null;
+  const scale = 10 ** digits;
+  return Math.round(value * scale) / scale;
+}
+
+/** The measure_mix result: plain numbers (null for silence), no series. */
+export function measurementJSON(
+  measured: ScoreMeasurement,
+  master: SongMaster | undefined,
+): Record<string, unknown> {
+  const { mix } = measured;
+  const loudness = mix.loudness;
+  const notes: string[] = [];
+  if (!Number.isFinite(loudness.integrated))
+    notes.push("silent: nothing to measure");
+  else {
+    // The limiter's own ceiling when one is set; otherwise -1 dBTP, or -2
+    // for a master louder than -14 LUFS (lossy encodes of loud, dense
+    // material make inter-sample overs).
+    const set = master?.limiter?.ceiling;
+    const safe = loudness.integrated > -14 ? -2 : -1;
+    const ceiling = typeof set === "number" ? set : safe;
+    if (loudness.truePeak > ceiling + 0.1)
+      notes.push(
+        typeof set === "number"
+          ? `true peak above the ${ceiling} dBTP ceiling`
+          : `true peak above ${safe} dBTP: lossy encodes may clip (keep -1 dBTP, -2 for masters louder than -14 LUFS)`,
+      );
+    if (mix.correlation < 0)
+      notes.push("negative correlation: parts cancel in mono");
+    if (mix.bands.sub > -3)
+      notes.push("sub band dominates; check the low end on small speakers");
+  }
+  if (measured.master?.target !== undefined && !measured.master.reached)
+    notes.push(
+      measured.master.integrated < measured.master.target
+        ? "target missed: the limiter has hit its plateau; add master tape (preset crush) or a lower glue threshold before it"
+        : "target missed: the mix is louder than the target allows",
+    );
+  return {
+    integrated: round(loudness.integrated),
+    shortTermMax: round(loudness.shortTermMax),
+    momentaryMax: round(loudness.momentaryMax),
+    range: round(loudness.range),
+    truePeak: round(loudness.truePeak),
+    samplePeak: round(loudness.samplePeak),
+    plr: round(mix.plr),
+    bands: Object.fromEntries(
+      Object.entries(mix.bands).map(([name, db]) => [name, round(db)]),
+    ),
+    correlation: round(mix.correlation, 2),
+    sideDb: round(mix.sideDb),
+    seconds: round(measured.seconds, 2),
+    sampleRate: measured.sampleRate,
+    loop: measured.loop,
+    master: master
+      ? {
+          chain: describeMaster(master),
+          ...(measured.master
+            ? {
+                gainDb: round(measured.master.gainDb),
+                ...(measured.master.target === undefined
+                  ? {}
+                  : {
+                      target: measured.master.target,
+                      reached: measured.master.reached,
+                    }),
+              }
+            : {}),
+        }
+      : null,
+    ...(notes.length ? { notes } : {}),
+  };
+}
+
+/** Measure with the window's decoded samples when it has them. */
+async function measureWith(
+  preview: PreviewHost | undefined,
+  score: TrackScore,
+  sampleRate: number,
+): Promise<ScoreMeasurement> {
+  return preview?.measure
+    ? await preview.measure(score, { sampleRate })
+    : measureScore(score, { sampleRate });
+}
+
+export const MASTER_TOOLS = Object.freeze([
+  {
+    name: "set_master",
+    description: `Edit the song master (after every track and bus) and its loudness target. Units run eq, glue, tape, width, limiter; each takes false (remove), true (defaults), a preset or {param: value}; omitted units stay. A named target (${TARGET_LIST}) also sets the limiter. off:true removes the master.`,
+    parameters: {
+      type: "object",
+      properties: {
+        ...UNIT_ARGS,
+        target: {
+          description: `Integrated LUFS (${MASTER_LIMITS.minTarget} to ${MASTER_LIMITS.maxTarget}), a name, or null to clear. The limiter's drive reaches it; without a limiter, gain stops at ${MASTER_LIMITS.safeCeiling} dBTP.`,
+          anyOf: [
+            { type: "number" },
+            { type: "string", enum: [...LOUDNESS_TARGET_NAMES] },
+            { type: "null" },
+          ],
+        },
+        off: {
+          type: "boolean",
+          description: "Remove the whole master.",
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const commands: MasterCommand[] = [];
+      if (args.off === true) commands.push({ type: "master-off" });
+      for (const unit of MASTER_UNITS)
+        commands.push(...unitCommands(unit, args[unit]));
+      const target = targetCommand(args.target);
+      if (target) commands.push(target);
+      for (const key of Object.keys(args))
+        if (key !== "off" && key !== "target" && !isMasterUnit(key))
+          throw new MasterToolError(`unknown argument ${key}`);
+      if (commands.length === 0)
+        throw new MasterToolError(
+          "pass a unit (eq, glue, tape, width, limiter), target or off",
+        );
+      let master: SongMaster | undefined = context.score.master;
+      try {
+        for (const command of commands)
+          master = normalizeMaster(nextMaster(master, command));
+      } catch (error) {
+        if (
+          error instanceof FxValidationError ||
+          error instanceof ScoreValidationError
+        )
+          throw new MasterToolError(error.message);
+        throw error;
+      }
+      return {
+        kind: "score",
+        operations: [{ type: "setMaster", master: master ?? null }],
+        summary: `master · ${describeMaster(master)}`.slice(0, 160),
+      };
+    },
+  },
+  {
+    name: "measure_mix",
+    description:
+      "Render and measure the song (read-only): integrated, short-term and momentary LUFS, loudness range, true peak, PLR, band balance (dB share), stereo correlation and side level, after the master. bypass_master:true measures before it.",
+    parameters: {
+      type: "object",
+      properties: {
+        bypass_master: {
+          type: "boolean",
+          description: "Measure without the master.",
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      if (
+        args.bypass_master !== undefined &&
+        typeof args.bypass_master !== "boolean"
+      )
+        throw new MasterToolError("bypass_master must be a boolean");
+      const bypass = args.bypass_master === true && !!context.score.master;
+      const score = bypass ? context.score.withMaster(null) : context.score;
+      return {
+        kind: "action",
+        summary: bypass
+          ? "measured the mix before the master"
+          : "measured the mix",
+        async run(action) {
+          // The bypassed reading stays at the mastered song's rate, so the
+          // before/after comparison is not a resampling artefact.
+          const measured = await measureWith(
+            action.preview,
+            score,
+            exportSampleRate(context.score),
+          );
+          const result = measurementJSON(measured, score.master);
+          const integrated = result.integrated;
+          return {
+            content: JSON.stringify(result),
+            summary:
+              integrated === null
+                ? "measured · silent"
+                : `measured · ${integrated} LUFS · ${result.truePeak} dBTP`,
+          };
+        },
+      };
+    },
+  },
+] satisfies AgentTool[]);

package/src/agent/models.ts

@@ -486,17 +486,17 @@ export async function loadLiveCatalog(
  * and `chatTools()` serialized, plus `compositionBrief` of a 3-track, 48-note
  * loop; see models.test.ts, which keeps these in step with the code):
  *
- * - system prompt ≈ 2.8 KB, tool schemas ≈ 21.9 KB, brief ≈ 1.2 KB typical
- *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 26 KB ≈ 6,500 tokens
+ * - system prompt ≈ 4.3 KB, tool schemas ≈ 38 KB, brief ≈ 1.6 KB typical
+ *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 44 KB ≈ 11,000 tokens
  *   per request at ~4 bytes per token;
  * - about 2 requests per prompt (tool calls, then a short reply), the second
  *   also carrying the first step's tool calls and results (≈ 0.6 KB);
  * - output ≈ 450 tokens of tool-call arguments and ≈ 150 of reply.
  *
- * So ≈ 13,200 input and ≈ 600 output tokens per prompt.
+ * So ≈ 22,100 input and ≈ 600 output tokens per prompt.
  */
 export const TYPICAL_PROMPT = Object.freeze({
-  inputTokens: 13_200,
+  inputTokens: 22_100,
   outputTokens: 600,
 });
 

package/src/agent/ops.ts

@@ -11,6 +11,8 @@ export type AgentOperation =
       start: number;
       duration: number;
       velocity: number;
+      /** Static offset from an `E4-14c` pitch; absent is 0. */
+      cents?: number;
     }
   | { type: "remove-note"; noteId: string }
   | {
@@ -21,6 +23,8 @@ export type AgentOperation =
         duration?: number;
         pitch?: number;
         velocity?: number;
+        /** 0 clears the offset. */
+        cents?: number;
       };
     }
   | { type: "set-tempo"; tempoBpm: number }
@@ -139,13 +143,27 @@ export function parsePrompt(prompt: string): AgentOperation | undefined {
       noteId: velocity[1]!,
       patch: { velocity: Number(velocity[2]) },
     };
+  const cents = text.match(
+    /^(?:cents|detune)\s+(?:note\s+)?([a-z0-9._-]{1,64})\s+([+-]?\d+(?:\.\d+)?)c?$/,
+  );
+  if (cents) {
+    const value = Number(cents[2]);
+    if (Math.abs(value) <= 1200)
+      return {
+        type: "update-note",
+        noteId: cents[1]!,
+        patch: { cents: value },
+      };
+  }
   const match = text.match(
-    /^(?:add|put)\s+(?:note\s+)?([a-g](?:#|b)?-?\d+)\s+(?:at\s+)?(\d+(?:\.\d+)?)\s*(?:for|dur|duration)?\s*(\d+(?:\.\d+)?)?$/,
+    /^(?:add|put)\s+(?:note\s+)?([a-g](?:#|b)?-?\d+)([+-]\d+(?:\.\d+)?c)?\s+(?:at\s+)?(\d+(?:\.\d+)?)\s*(?:for|dur|duration)?\s*(\d+(?:\.\d+)?)?$/,
   );
   if (!match) return undefined;
   const pitch = pitchToMidi(match[1] ?? "c4");
-  const start = Number(match[2] ?? 0);
-  const duration = Number(match[3] ?? 1);
+  const offset = match[2] ? Number(match[2].slice(0, -1)) : 0;
+  const start = Number(match[3] ?? 0);
+  const duration = Number(match[4] ?? 1);
+  if (!(Math.abs(offset) <= 1200)) return undefined;
   if (
     !Number.isFinite(pitch) ||
     !Number.isFinite(start) ||
@@ -153,5 +171,12 @@ export function parsePrompt(prompt: string): AgentOperation | undefined {
     duration <= 0
   )
     return undefined;
-  return { type: "add-note", pitch, start, duration, velocity: 0.8 };
+  return {
+    type: "add-note",
+    pitch,
+    start,
+    duration,
+    velocity: 0.8,
+    ...(offset !== 0 ? { cents: offset } : {}),
+  };
 }

package/src/agent/planner.ts

@@ -1,5 +1,7 @@
 import { normalizeSynth } from "../../core/synth.ts";
+import { normalizeSongTime, normalizeTrackTime } from "../../core/tempo.ts";
 import { normalizeFx } from "../../core/fx.ts";
+import { normalizeMaster } from "../../core/master.ts";
 import {
   SCORE_LIMITS,
   automationRange,
@@ -10,8 +12,12 @@ import {
   normalizeSampler,
   normalizeRhythm,
   scoreFromJSON,
+  type NotePatch,
+  type FormEntry,
   type ScoreOperation,
+  type Section,
 } from "../../core/score.ts";
+import { NOTE_EXPRESSION_FIELDS } from "../../core/expression.ts";
 import { DRUM_VOICES } from "../../core/drums.ts";
 import { synthKit } from "../../core/kits.ts";
 
@@ -131,6 +137,34 @@ function parseOperation(value: unknown): ScoreOperation {
   ) {
     return { type: "setMeter", beatsPerBar: value.beatsPerBar };
   }
+  if (value.type === "setTime") {
+    // The reducer re-validates; this only bounds the shape.
+    const time = value.time === null ? null : normalizeSongTime(value.time);
+    return { type: "setTime", time: time ?? null };
+  }
+  // The master reuses its bounded validator; null removes it.
+  if (value.type === "setMaster" && value.master !== undefined)
+    return { type: "setMaster", master: normalizeMaster(value.master) ?? null };
+  if (
+    value.type === "setSections" &&
+    Array.isArray(value.sections) &&
+    value.sections.length <= SCORE_LIMITS.maxSections &&
+    (value.form === undefined ||
+      (Array.isArray(value.form) &&
+        value.form.length <= SCORE_LIMITS.maxFormEntries)) &&
+    (value.loopSection === undefined ||
+      value.loopSection === null ||
+      (typeof value.loopSection === "string" &&
+        value.loopSection.length <= SCORE_LIMITS.maxSectionNameLength))
+  ) {
+    // Shapes are validated by the reducer (TrackScore normalizes sections).
+    return {
+      type: "setSections",
+      sections: value.sections as readonly Section[],
+      form: (value.form ?? []) as readonly FormEntry[],
+      loopSection: (value.loopSection ?? null) as string | null,
+    };
+  }
   if (
     value.type === "updateTrack" &&
     typeof value.trackId === "string" &&
@@ -168,6 +202,8 @@ function parseOperation(value: unknown): ScoreOperation {
     if (patch.fx !== undefined) safe.fx = normalizeFx(patch.fx) ?? null;
     if (patch.synth !== undefined)
       safe.synth = normalizeSynth(patch.synth) ?? null;
+    if (patch.time !== undefined)
+      safe.time = normalizeTrackTime(patch.time) ?? null;
     return { type: "updateTrack", trackId: value.trackId, patch: safe };
   }
   if (
@@ -210,7 +246,7 @@ function parseOperation(value: unknown): ScoreOperation {
     isRecord(value.patch)
   ) {
     const patch = value.patch;
-    const safe: Record<string, number> = {};
+    const safe: Record<string, unknown> = {};
     for (const key of [
       "startTick",
       "durationTicks",
@@ -220,7 +256,14 @@ function parseOperation(value: unknown): ScoreOperation {
       if (typeof patch[key] === "number" && Number.isFinite(patch[key]))
         safe[key] = patch[key];
     }
-    return { type: "updateNote", noteId: value.noteId, patch: safe };
+    // Expression fields pass through; the reducer validates them.
+    for (const key of NOTE_EXPRESSION_FIELDS)
+      if (key in patch) safe[key] = patch[key];
+    return {
+      type: "updateNote",
+      noteId: value.noteId,
+      patch: safe as NotePatch,
+    };
   }
   if (value.type === "addNote" && isRecord(value.note)) {
     const note = value.note;

package/src/agent/preview-tool.ts

@@ -22,6 +22,7 @@ import {
   type SoundStats,
 } from "../audio/preview.ts";
 import { renderScorePcm, type RenderedAudio } from "../audio/wav.ts";
+import type { ScoreMeasurement } from "../audio/measure.ts";
 import type {
   ActionContext,
   AgentTool,
@@ -51,6 +52,14 @@ export type PreviewHost = Readonly<{
   render?: (score: TrackScore) => Promise<RenderedAudio> | RenderedAudio;
   /** Play the snippet once; returns false when nothing could sound. */
   play?: (audio: RenderedAudio) => boolean | Promise<boolean>;
+  /**
+   * Render and measure for measure_mix (the host adds decoded samples), at
+   * `sampleRate` when given and the score's export rate otherwise.
+   */
+  measure?: (
+    score: TrackScore,
+    options?: Readonly<{ sampleRate?: number }>,
+  ) => Promise<ScoreMeasurement>;
 }>;
 
 /** Thrown for a candidate the tool refuses; nothing is rendered. */
@@ -217,22 +226,31 @@ export function previewSoundTool(
             : after.region;
           const render =
             action.preview?.render ?? ((value) => renderScorePcm(value));
-          const snippet = async (value: TrackScore) => {
+          const snippet = async (value: TrackScore, masterGainDb?: number) => {
             const preview = previewScore(value, trackId, {
               context: inContext,
               region,
+              ...(masterGainDb === undefined ? {} : { masterGainDb }),
             });
             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;
+          // The after snippet plays the master at the drive the before one
+          // used, so a level change is not normalized away by the target
+          // (unless the change is to the master itself).
+          const fixedGain = changes.some(
+            (change) => change.tool === "set_master",
+          )
+            ? undefined
+            : before?.audio.master?.gainDb;
+          const next = await snippet(candidate.score, fixedGain);
+          if (!next) throw new PreviewToolError(`unknown track ${trackId}`);
           let played = false;
           if (play && action.preview?.play)
             played = await action.preview.play(next.audio);