@hraness/dawg 0.4.1 → 0.6.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 ≈ 7 KB, tool schemas ≈ 51 KB, brief ≈ 1.6 KB typical
+ *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 59 KB ≈ 14,800 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 ≈ 29,800 input and ≈ 600 output tokens per prompt.
  */
 export const TYPICAL_PROMPT = Object.freeze({
-  inputTokens: 13_200,
+  inputTokens: 29_800,
   outputTokens: 600,
 });
 

package/src/agent/ops.ts

@@ -1,4 +1,9 @@
+import { resolveInstrumentWord } from "../../core/instruments.ts";
 import { pitchToMidi } from "../../core/pitch.ts";
+import {
+  instrumentPatchForWord,
+  type TrackModal,
+} from "../../core/resonators.ts";
 import { SCORE_LIMITS } from "../../core/score.ts";
 
 export { pitchToMidi };
@@ -11,6 +16,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 +28,8 @@ export type AgentOperation =
         duration?: number;
         pitch?: number;
         velocity?: number;
+        /** 0 clears the offset. */
+        cents?: number;
       };
     }
   | { type: "set-tempo"; tempoBpm: number }
@@ -30,11 +39,16 @@ export type AgentOperation =
       type: "track";
       patch: {
         instrument?: string;
+        string?: { preset: string };
+        /** 0.6: a modal preset word (`instrument vibes`) sets this too. */
+        modal?: TrackModal;
         muted?: boolean;
         volume?: number;
         pan?: number;
         name?: string;
       };
+      /** The instrument word as typed (a guitar alias also loads its rig). */
+      word?: string;
     }
   | {
       type: "automation";
@@ -70,8 +84,14 @@ export function parsePrompt(prompt: string): AgentOperation | undefined {
   const instrument = text.match(
     /^(?:instrument|sound|voice)\s+([a-z0-9._ -]{1,64})$/,
   );
-  if (instrument)
-    return { type: "track", patch: { instrument: instrument[1]!.trim() } };
+  if (instrument) {
+    const word = instrument[1]!.trim();
+    return {
+      type: "track",
+      patch: instrumentPatch(word),
+      ...(resolveInstrumentWord(word)?.fx ? { word } : {}),
+    };
+  }
   if (/^(?:mute|silence)\b/.test(text))
     return { type: "track", patch: { muted: true } };
   if (/^(?:unmute|unsilence)\b/.test(text))
@@ -139,13 +159,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 +187,33 @@ 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 } : {}),
+  };
+}
+
+/**
+ * The track patch an instrument word means: a 0.6 resolver word for the
+ * string engine also writes its preset (`instrument nylon` plays the nylon
+ * string); every other word stores the instrument as before.
+ */
+export function instrumentPatch(word: string): {
+  instrument: string;
+  string?: { preset: string };
+  modal?: TrackModal;
+} {
+  const meaning = resolveInstrumentWord(word);
+  if (!meaning) return { instrument: word };
+  if (meaning.field === "modal") return instrumentPatchForWord(word);
+  if (meaning.field === "string" && meaning.preset)
+    return {
+      instrument: meaning.instrument,
+      string: { preset: meaning.preset },
+    };
+  return { instrument: meaning.instrument };
 }

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,
@@ -35,10 +36,15 @@ export const PREVIEWABLE_TOOLS: readonly string[] = Object.freeze([
   "set_mix",
   "set_automation",
   "set_fx",
+  "set_rig",
   "set_synth",
+  "set_string",
+  "set_modal",
   "set_sample",
+  "fit_sample",
   "set_effects",
   "set_wavetable",
+  "set_granular",
   "set_drum_kit",
   "use_sound",
 ]);
@@ -51,6 +57,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. */
@@ -145,7 +159,7 @@ export function previewSoundTool(
   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.",
+      "Hear a track, or a candidate sound change, without committing it. changes: sound tool calls to try ({tool, args} for set_fx, set_rig, set_synth, set_string, set_modal, set_wavetable, set_instrument, set_sample, fit_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: {
@@ -217,22 +231,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);