@hraness/dawg 0.5.0 → 0.6.1

package/src/main.ts

@@ -1,4 +1,8 @@
 #!/usr/bin/env bun
+import {
+  isUnknownInstrument,
+  plainSineAdvice,
+} from "./audio/instrument-check.ts";
 import { randomUUID } from "node:crypto";
 import { readFileSync, writeSync } from "node:fs";
 import { readFile, stat, writeFile } from "node:fs/promises";
@@ -54,8 +58,47 @@ import {
   applyExpressionCommand,
   parseExpressionCommand,
 } from "./commands/expression.ts";
-import { applyFxCommand, parseFxCommand } from "./commands/fx.ts";
+import {
+  applyFxCommand,
+  parseFxCommand,
+  unknownFxMessage,
+} from "./commands/fx.ts";
+import {
+  applyRigCommand,
+  parseRigCommand,
+  rigTrackFields,
+  rigWordPatch,
+} from "./commands/rig.ts";
+import {
+  applyGuitarCommand,
+  applyStrumCommand,
+  parseGuitarCommand,
+  parseStrumCommand,
+} from "./commands/strum.ts";
+import {
+  applyModalCommand,
+  modalListLines,
+  parseModalCommand,
+} from "./commands/modal.ts";
+import {
+  applyWindCommand,
+  parseWindCommand,
+  windListLines,
+} from "./commands/wind.ts";
 import { applySynthCommand, parseSynthCommand } from "./commands/synth.ts";
+import { applyStringCommand, parseStringCommand } from "./commands/string.ts";
+import { instrumentPatchForWord, isModalWord } from "../core/resonators.ts";
+import {
+  applyGranularCommand,
+  granularTrackPreset,
+  grainSrcHint,
+  parseGranularCommand,
+} from "./commands/granular.ts";
+import {
+  applyKeysCommand,
+  newPianoTrack,
+  parseKeysCommand,
+} from "./commands/keys.ts";
 import {
   applyTuningCommand,
   importTuningFile,
@@ -94,9 +137,14 @@ import {
   samplerTarget,
   voiceNameFrom,
 } from "./commands/sample.ts";
+import { applyFitCommand, fitVoice, parseFitCommand } from "./commands/fit.ts";
+import { applyShiftCommand, parseShiftCommand } from "./commands/shift.ts";
+import { parseResampleCommand, runResample } from "./commands/resample.ts";
+import { suggestFitMode } from "./audio/dsp/onset.ts";
 import {
   SampleLibrary,
   hasSamplerTracks,
+  sampleKey,
   type SampleBank,
   type SampleProblem,
 } from "./audio/samples.ts";
@@ -216,6 +264,7 @@ import {
   addNote,
   applyScoreOperation,
   createScore,
+  isSamplerInstrument,
   PACK_PREFIX,
   scoreFromJSON,
   SCORE_LIMITS,
@@ -260,6 +309,9 @@ function parsesLocally(text: string): boolean {
     parseRhythmCommand,
     parseFxCommand,
     parseSynthCommand,
+    parseStringCommand,
+    parseGranularCommand,
+    parseKeysCommand,
     parseExpressionCommand,
     parseMasterCommand,
     (value: string) => parseSectionCommand(value, score),
@@ -267,9 +319,17 @@ function parsesLocally(text: string): boolean {
     parseKitCommand,
     parsePackCommand,
     parseSampleCommand,
+    parseFitCommand,
+    parseShiftCommand,
+    parseResampleCommand,
     parseWavetableCommand,
     parseTimeCommand,
     parseTuningCommand,
+    parseRigCommand,
+    parseModalCommand,
+    parseGuitarCommand,
+    parseStrumCommand,
+    parseWindCommand,
   ].some((parse) => parse(text) !== undefined);
 }
 
@@ -416,7 +476,13 @@ if (!demo && process.env.DAWG_AI !== "0" && stdout.isTTY)
 
 const initial = createScore({
   tracks: [
-    { id: requestedTrack, name: requestedTrack, instrument: initialInstrument },
+    {
+      id: requestedTrack,
+      name: requestedTrack,
+      instrument: initialInstrument,
+      // `dawg jangle`: a guitar alias starts with its voice and rig.
+      ...rigTrackFields(requestedTrack),
+    },
   ],
 });
 const sessionOptions: { sessionId?: string; setCurrent: boolean } = {
@@ -439,6 +505,22 @@ const freshWorkspace = !(await stat(join(process.cwd(), ".dawg")).then(
   () => true,
   () => false,
 ));
+// Decode the import before a session exists, so a bad file is one line.
+let importedScore: TrackScore | undefined;
+if (importPath) {
+  try {
+    importedScore = decodeLoop(await readLoopFile(importPath));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const midi = /\.midi?$/i.test(importPath)
+      ? " · MIDI files are not imported; --import takes a .track.json loop"
+      : "";
+    process.stderr.write(
+      `dawg: cannot import ${importPath} · ${reason.split("\n")[0]!.slice(0, 160)}${midi}\n`,
+    );
+    process.exit(1);
+  }
+}
 const session = await ensureSession(initial.toJSON(), sessionOptions);
 // dawgd when connected, the file-lock path otherwise (see src/session/port.ts).
 let port = await openSessionPort<ReturnType<TrackScore["toJSON"]>>({
@@ -451,9 +533,8 @@ let port = await openSessionPort<ReturnType<TrackScore["toJSON"]>>({
 let record: SessionRecord<ReturnType<TrackScore["toJSON"]>> =
   port.mode === "daemon" ? await port.load() : session.record;
 let score = scoreFromJSON(record.composition);
-if (importPath) {
-  const imported = decodeLoop(await readLoopFile(importPath));
-  score = imported;
+if (importPath && importedScore) {
+  score = importedScore;
   record = await port.append(
     record,
     {
@@ -1608,7 +1689,11 @@ async function submit(prompt: string): Promise<string | Receipt> {
   }
   const chordsCommand = command.match(/^\/chords(?:\s+(.+))?$/i);
   if (chordsCommand) {
-    const result = applyChordsCommand(chordSettings, chordsCommand[1] ?? "");
+    const result = applyChordsCommand(
+      chordSettings,
+      chordsCommand[1] ?? "",
+      score.tempoBpm,
+    );
     return result.ok ? ok(result.message) : fail(result.message);
   }
   const countIn = command.match(/^\/count-?in\s+([0-2])$/i);
@@ -1660,6 +1745,15 @@ async function submit(prompt: string): Promise<string | Receipt> {
     /^\/?(?:add\s+)?track\s+([a-z0-9._-]{1,64})$/i,
   );
   if (trackCommand) return focusTrack(trackCommand[1]!.toLowerCase());
+  // `track cloud grain hold`: focus (or create) a track and grain it.
+  const grainTrack = command.match(
+    /^\/?track\s+([a-z0-9._-]{1,64})\s+(grain\s+.+)$/i,
+  );
+  if (grainTrack && parseGranularCommand(grainTrack[2]!)) {
+    const focused = await focusTrack(grainTrack[1]!.toLowerCase());
+    if (requestedTrack !== grainTrack[1]!.toLowerCase()) return focused;
+    return submit(grainTrack[2]!);
+  }
   // `/track piano b`: a name with spaces focuses the track of that name, or
   // creates `piano-b` named "piano b".
   const namedTrack = command.match(/^\/track\s+([a-z0-9._ -]{1,64})$/i);
@@ -1672,6 +1766,18 @@ async function submit(prompt: string): Promise<string | Receipt> {
   }
   const sample = parseSampleCommand(command);
   if (sample) return sampleCommand(sample);
+  const fit = parseFitCommand(command);
+  if (fit) return fitCommand(fit);
+  const shift = parseShiftCommand(command);
+  if (shift) {
+    const result = applyShiftCommand(score, requestedTrack, shift);
+    if (!result.ok) return fail(result.message);
+    await commitScore(result.next, "sample.set", { trackId: requestedTrack });
+    await projectSync?.flushScore();
+    return ok(result.message);
+  }
+  const resample = parseResampleCommand(command);
+  if (resample) return resampleCommand(resample);
   const pack = parsePackCommand(command);
   if (pack) return packCommand(pack);
   const pattern = parsePatternCommand(command);
@@ -1706,6 +1812,34 @@ async function submit(prompt: string): Promise<string | Receipt> {
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
   }
+  const guitar = parseGuitarCommand(command);
+  if (guitar) {
+    if (guitar.type !== "guitar-show" && guitar.type !== "guitar-hint")
+      await materializeDraft();
+    const result = applyGuitarCommand(score, requestedTrack, guitar);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const strum = parseStrumCommand(command);
+  if (strum) {
+    if (strum.type === "strum") await materializeDraft();
+    const result = applyStrumCommand(score, requestedTrack, strum, () =>
+      randomUUID().slice(0, 12),
+    );
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const rig = parseRigCommand(command);
+  if (rig) {
+    if (rig.type !== "rig-show" && rig.type !== "rig-hint")
+      await materializeDraft();
+    const result = applyRigCommand(score, requestedTrack, rig);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const fx = parseFxCommand(command);
   if (fx) {
     if (fx.type !== "fx-list") await materializeDraft();
@@ -1725,6 +1859,8 @@ async function submit(prompt: string): Promise<string | Receipt> {
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
   }
+  const unknownFx = unknownFxMessage(command);
+  if (unknownFx) return fail(unknownFx);
   const expression = parseExpressionCommand(command);
   if (expression) {
     if (expression.type !== "show" && expression.type !== "invalid")
@@ -1736,6 +1872,38 @@ async function submit(prompt: string): Promise<string | Receipt> {
   }
   const tuning = parseTuningCommand(command);
   if (tuning) return tuningCommand(tuning);
+  const keysCommand = parseKeysCommand(command);
+  if (keysCommand) {
+    const reads =
+      keysCommand.type === "keys-list" || keysCommand.type === "keys-presets";
+    if (!reads) await materializeDraft();
+    const result = applyKeysCommand(score, requestedTrack, keysCommand);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const modal = parseModalCommand(command);
+  if (modal) {
+    if (modal.type === "modal-list")
+      tui.openText("modal presets", modalListLines());
+    if (modal.type !== "modal-show" && modal.type !== "modal-list")
+      await materializeDraft();
+    const result = applyModalCommand(score, requestedTrack, modal);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const windCommand = parseWindCommand(command);
+  if (windCommand) {
+    if (windCommand.type === "wind-list")
+      tui.openText("wind presets", windListLines());
+    if (windCommand.type !== "wind-show" && windCommand.type !== "wind-list")
+      await materializeDraft();
+    const result = applyWindCommand(score, requestedTrack, windCommand);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const synth = parseSynthCommand(command);
   if (synth) {
     if (synth.type !== "synth-list") await materializeDraft();
@@ -1744,6 +1912,29 @@ async function submit(prompt: string): Promise<string | Receipt> {
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
   }
+  const stringCommand = parseStringCommand(command);
+  if (stringCommand) {
+    if (
+      stringCommand.type !== "string-list" &&
+      stringCommand.type !== "string-presets"
+    )
+      await materializeDraft();
+    const result = applyStringCommand(score, requestedTrack, stringCommand);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const grainHint = grainSrcHint(command);
+  if (grainHint) return fail(grainHint);
+  const grain = parseGranularCommand(command);
+  if (grain) {
+    if (grain.type !== "grain-list" && grain.type !== "grain-presets")
+      await materializeDraft();
+    const result = applyGranularCommand(score, requestedTrack, grain);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const masterCommand = parseMasterCommand(command);
   if (masterCommand) {
     if (masterCommand.type === "master-measure")
@@ -1911,7 +2102,16 @@ async function submit(prompt: string): Promise<string | Receipt> {
     const next = score.withTempo(parsed.tempoBpm);
     await commitScore(next, "score.tempo", { tempoBpm: parsed.tempoBpm });
     clock.follow(next);
-    return `tempo · ${next.tempoBpm} BPM`;
+    // A bare `bpm <n>` stays song tempo; on a sampler track say where the
+    // sample's own tempo lives (`/bpm`, 0.6 fit).
+    const focused = next.tracks.find((t) => t.id === requestedTrack);
+    const samplerHint =
+      /^\s*bpm\b/i.test(prompt) &&
+      focused?.sampler &&
+      isSamplerInstrument(focused.instrument)
+        ? ` · song tempo · the sample's own tempo is /bpm ${parsed.tempoBpm}`
+        : "";
+    return `tempo · ${next.tempoBpm} BPM${samplerHint}`;
   }
   if (parsed.type === "add-track") return focusTrack(parsed.trackId);
   if (parsed.type === "set-bars" || parsed.type === "extend-bars") {
@@ -1924,15 +2124,45 @@ async function submit(prompt: string): Promise<string | Receipt> {
     return `bars · ${bars}`;
   }
   if (parsed.type === "track") {
+    // An unknown word would store and play a plain sine: say so instead.
+    const word = parsed.patch.instrument;
+    if (word !== undefined && isUnknownInstrument(word)) {
+      const advice = plainSineAdvice(word) ?? "";
+      const near = advice.match(/did you mean (\S+)\?/)?.[1];
+      return fail(
+        `instrument ${truncateForCard(word)} · not a dawg instrument${near ? ` · did you mean ${near}?` : ""} · /menu sounds lists them`,
+      );
+    }
+    // `instrument jangle`: a guitar alias also loads its rig.
+    const patch = parsed.word
+      ? {
+          ...parsed.patch,
+          ...rigWordPatch(
+            parsed.word,
+            score.tracks.find((t) => t.id === requestedTrack)?.fx,
+          ),
+        }
+      : parsed.patch;
     const next = applyScoreOperation(score, {
       type: "updateTrack",
       trackId: requestedTrack,
-      patch: parsed.patch,
+      patch,
     });
     await commitScore(next, "score.track", {
       trackId: requestedTrack,
-      patch: parsed.patch,
+      patch,
     });
+    // Plain `marimba` keeps the legacy tone; point at the mallet engine.
+    if (parsed.patch.instrument === "marimba" && !("modal" in parsed.patch))
+      return `track · ${requestedTrack} · marimba (legacy tone) · modal marimba for the mallet engine`;
+    // Plain `wind` keeps the legacy tone; point at the wind engine.
+    if (parsed.patch.instrument === "wind" && !("wind" in parsed.patch))
+      return `track · ${requestedTrack} · wind (legacy tone) · wind flute (or sax, trumpet …) for the wind engine`;
+    const sine =
+      word !== undefined && !("string" in parsed.patch)
+        ? plainSineAdvice(word)
+        : undefined;
+    if (sine) return `track · ${requestedTrack} · ${sine}`;
     return `track · ${requestedTrack}`;
   }
   if (parsed.type === "automation") {
@@ -2072,14 +2302,28 @@ async function focusTrack(trackId: string): Promise<Receipt> {
     )
   )
     return warn(`${trackId} is open in another window`);
-  const exists = score.tracks.some((track) => track.id === trackId);
+  const existing = score.tracks.find((track) => track.id === trackId);
+  const exists = existing !== undefined;
+  // `track cloud`, `track hold-2`: a new granular track with that preset.
+  const grainPreset = granularTrackPreset(trackId);
   if (!exists) {
     const next = applyScoreOperation(score, {
       type: "addTrack",
       track: {
         id: trackId,
         name: trackId,
-        instrument: isDrumInstrument(trackId) ? "kit" : "sine",
+        instrument: grainPreset
+          ? "granular"
+          : isDrumInstrument(trackId)
+            ? "kit"
+            : "sine",
+        // `track jangle`, `track gtr-metal`…: a guitar voice and its rig.
+        ...rigTrackFields(trackId),
+        ...(grainPreset ? { granular: { preset: grainPreset } } : {}),
+        // `/track piano` (or grand, felt…) starts on the modelled piano.
+        ...newPianoTrack(trackId),
+        // `track vibes`: a 0.6 modal word names the track and its preset.
+        ...(isModalWord(trackId) ? instrumentPatchForWord(trackId) : {}),
       },
     });
     await commitScore(next, "track.create", { trackId });
@@ -2087,7 +2331,17 @@ async function focusTrack(trackId: string): Promise<Receipt> {
   await port.focus(trackId);
   requestedTrack = trackId;
   draftTrack = false;
-  return ok(exists ? `track · ${trackId}` : `track created · ${trackId}`);
+  if (exists && grainPreset && existing.instrument !== "granular")
+    return warn(
+      `track · ${trackId} is a ${existing.instrument} track · grain ${grainPreset} makes it granular`,
+    );
+  return ok(
+    exists
+      ? `track · ${trackId}`
+      : grainPreset
+        ? `track created · ${trackId} · granular ${grainPreset} · nothing to download`
+        : `track created · ${trackId}`,
+  );
 }
 
 /** Decode every sampler voice (cached) and return what failed to load. */
@@ -2173,6 +2427,64 @@ async function tuningCommand(command: TuningCommand): Promise<Receipt> {
   return result.ok ? ok(result.message) : fail(result.message);
 }
 
+/** `/fitmode`, `/bpm`, `/len` on the focused sampler voice (0.6). */
+async function fitCommand(
+  command: NonNullable<ReturnType<typeof parseFitCommand>>,
+): Promise<Receipt> {
+  let suggested: "beats" | "tones" | undefined;
+  if (command.control === "fitmode" && command.value === undefined) {
+    const target = fitVoice(score, requestedTrack, command.voice);
+    if ("error" in target) return fail(target.error);
+    const decoded = liveSampleBank?.voices.get(
+      sampleKey(requestedTrack, target.voice),
+    );
+    if (!decoded)
+      return warn(
+        "fit · the sample is still loading · fitmode repitch|beats|tones",
+      );
+    suggested = suggestFitMode(decoded.mono, decoded.sampleRate);
+  }
+  const result = applyFitCommand(score, requestedTrack, command, suggested);
+  if (!result.ok) return fail(result.message);
+  await commitScore(result.next, "sample.set", { trackId: requestedTrack });
+  await projectSync?.flushScore();
+  return ok(
+    suggested
+      ? `${result.message} · suggested from the sound (${suggested === "beats" ? "hits" : "held tones"})`
+      : result.message,
+  );
+}
+
+async function resampleCommand(
+  command: NonNullable<ReturnType<typeof parseResampleCommand>>,
+): Promise<Receipt> {
+  await materializeDraft();
+  // The source's own samples must be loaded for the render.
+  if (hasSamplerTracks(score)) await sampleProblems(score);
+  const result = await runResample({
+    projectRoot: process.cwd(),
+    score,
+    command,
+    ...(liveSampleBank ? { samples: liveSampleBank } : {}),
+  });
+  if (!result.ok) return fail(result.message);
+  const problems = (await sampleProblems(result.next)).filter(
+    (problem) =>
+      problem.trackId === result.trackId && problem.level === "error",
+  );
+  if (problems.length > 0) return fail(`resample · ${problems[0]!.message}`);
+  await commitScore(result.next, "resample", {
+    trackId: result.trackId,
+    src: result.src,
+    sha256: result.sha256,
+  });
+  await port.focus(result.trackId);
+  requestedTrack = result.trackId;
+  draftTrack = false;
+  await projectSync?.flushScore();
+  return ok(result.message);
+}
+
 async function sampleCommand(
   command: NonNullable<ReturnType<typeof parseSampleCommand>>,
 ): Promise<Receipt> {
@@ -2965,7 +3277,11 @@ function stagedChordSettings(): ChordSettings | undefined {
   if (chords.length === 0) return undefined;
   const settings = { ...chordSettings };
   for (const command of chords)
-    applyChordsCommand(settings, command.match(CHORDS_COMMAND)![1]!);
+    applyChordsCommand(
+      settings,
+      command.match(CHORDS_COMMAND)![1]!,
+      score.tempoBpm,
+    );
   return settings;
 }
 
@@ -3022,7 +3338,11 @@ async function applyStaged(
   const chords = command.trim().match(CHORDS_COMMAND);
   if (chords) {
     // Window state: checked on a copy; kept settings apply on Enter.
-    const result = applyChordsCommand({ ...chordSettings }, chords[1]!);
+    const result = applyChordsCommand(
+      { ...chordSettings },
+      chords[1]!,
+      base.tempoBpm,
+    );
     return { next: base, ok: result.ok, message: result.message };
   }
   await prefetchStaged(base, command);
@@ -3215,7 +3535,11 @@ async function keepStaged(): Promise<Receipt> {
     CHORDS_COMMAND.test(command),
   );
   for (const command of chordCommands)
-    applyChordsCommand(chordSettings, command.match(CHORDS_COMMAND)![1]!);
+    applyChordsCommand(
+      chordSettings,
+      command.match(CHORDS_COMMAND)![1]!,
+      score.tempoBpm,
+    );
   const scoreCommands = taken.commands.filter(
     (command) => !CHORDS_COMMAND.test(command),
   );

package/src/project/check.ts

@@ -8,6 +8,11 @@ import {
   formatDiagnostic,
   type Diagnostic,
 } from "../../core/sdk/eval.ts";
+import {
+  legacyResonatorWarnings,
+  modalPairWarnings,
+} from "../../core/resonators.ts";
+import { plainSineWarnings } from "../audio/instrument-check.ts";
 import { isProject } from "./init.ts";
 import { typecheckProject } from "./typecheck.ts";
 
@@ -23,6 +28,8 @@ export type CheckReport = Readonly<{
   evalMs: number;
   tracks: number;
   notes: number;
+  /** Advice that does not fail the check (0.6: legacy instrument words). */
+  warnings: readonly string[];
 }>;
 
 /** Runs both checks on `project`; never throws for project problems. */
@@ -45,6 +52,15 @@ export async function checkProject(
     evalMs: evaluated.ms,
     tracks: evaluated.ok ? evaluated.score.tracks.length : 0,
     notes: evaluated.ok ? evaluated.score.notes.length : 0,
+    warnings: Object.freeze(
+      evaluated.ok
+        ? [
+            ...legacyResonatorWarnings(evaluated.score.tracks),
+            ...modalPairWarnings(evaluated.score.tracks),
+            ...plainSineWarnings(evaluated.score.tracks),
+          ]
+        : [],
+    ),
   });
 }
 
@@ -65,6 +81,7 @@ export async function runCheckCommand(
   const report = await checkProject(project, deps);
   for (const diagnostic of report.diagnostics)
     stderr.write(`${formatDiagnostic(diagnostic)}\n`);
+  for (const warning of report.warnings) stderr.write(`warning: ${warning}\n`);
   if (report.ok) {
     stdout.write(
       `ok · ${report.tracks} track${report.tracks === 1 ? "" : "s"}, ${report.notes} note${

package/src/render.ts

@@ -8,7 +8,12 @@
 import { createHash } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { scoreFromJSON, type TrackScore } from "../core/score.ts";
+import {
+  scoreFromJSON,
+  ScoreValidationError,
+  withNoteCap,
+  type TrackScore,
+} from "../core/score.ts";
 import { decodeLoop } from "../core/loop.ts";
 import { scoreToMidi } from "../core/midi.ts";
 import { RENDER_CHANNELS, encodeWav, withWavCues } from "./audio/wav.ts";
@@ -19,7 +24,12 @@ import {
   measurementLine,
   parseMasterCommand,
 } from "./commands/master.ts";
-import { bakeTrackTime, findSection, sectionScore } from "../core/sections.ts";
+import {
+  BAKED_NOTE_CAP,
+  bakeTrackTime,
+  findSection,
+  sectionScore,
+} from "../core/sections.ts";
 import {
   exportScore,
   renderArrangedPcm,
@@ -109,7 +119,9 @@ export async function runRenderCommand(
       return 1;
     }
     // One section as it plays when looped: its mutes and variations, no form.
-    score = sectionScore(bakeTrackTime(score), section);
+    score = withNoteCap(BAKED_NOTE_CAP, () =>
+      sectionScore(bakeTrackTime(score), section),
+    );
   }
   if (/\.midi?$/i.test(target)) {
     // MIDI carries notes, not audio: the master and loudness flags do not apply.
@@ -156,6 +168,16 @@ export async function runRenderCommand(
     samples = await new SampleLibrary({ projectRoot: workspace }).load(score);
     for (const problem of samples.problems)
       stderr.write(`sample ${problem.level} · ${problem.message}\n`);
+    // A voice that cannot load (a missing file, a pin that no longer
+    // matches) would render as silence: fail rather than write a song with
+    // a part missing.
+    const failed = samples.problems.filter((p) => p.level === "error").length;
+    if (failed > 0) {
+      stderr.write(
+        `render failed · ${failed} sample ${failed === 1 ? "voice" : "voices"} could not load · fix or re-pick ${failed === 1 ? "it" : "them"} and render again\n`,
+      );
+      return 1;
+    }
   }
   // A song with a master is a deliverable: 48 kHz unless --rate says
   // otherwise; a plain song keeps the engine's rate, as dawg 0.4 wrote it.
@@ -172,7 +194,14 @@ export async function runRenderCommand(
     );
     return 2;
   }
-  const audio = renderArrangedPcm(score, { samples, sampleRate });
+  let audio;
+  try {
+    audio = renderArrangedPcm(score, { samples, sampleRate });
+  } catch (error) {
+    if (!(error instanceof ScoreValidationError)) throw error;
+    stderr.write(`render failed · ${error.message}\n`);
+    return 1;
+  }
   let wav = encodeWav(audio.pcm, audio.sampleRate, RENDER_CHANNELS);
   // Section starts as cue points (a --section render is one section).
   if (only === undefined)
@@ -200,6 +229,15 @@ export async function runRenderCommand(
     `rendered · ${target} · ${seconds.toFixed(2)} s · ${wav.byteLength} bytes · ${sha}\n`,
   );
   if (credits) stdout.write(`credits · ${credits}\n`);
+  const clipped = clippedSamples(audio.pcm);
+  if (clipped > 0)
+    stderr.write(
+      `warning · ${clipped} ${clipped === 1 ? "sample clips" : "samples clip"} at full scale · ${
+        audio.master
+          ? "add master limiter or lower the master gain"
+          : "lower track volumes or add a master with a limiter (master streaming, or master: { limiter: {} } in song.ts)"
+      }\n`,
+    );
   if (options.has("--measure"))
     stdout.write(
       `loudness · ${measurementLine(measureRendered(audio, false).mix, audio.master)}\n`,
@@ -209,6 +247,13 @@ export async function runRenderCommand(
   return 0;
 }
 
+/** Samples at or past 16-bit full scale: the mix bus hit the rails. */
+export function clippedSamples(pcm: Int16Array): number {
+  let count = 0;
+  for (const value of pcm) if (value >= 32_767 || value <= -32_768) count += 1;
+  return count;
+}
+
 async function loadScore(
   workspace: string,
   options: ReadonlyMap<string, string>,