@hraness/dawg 0.4.0 → 0.5.0

package/core/sdk/eval-child.ts

@@ -1,16 +1,19 @@
 /**
  * Runs inside the evaluation subprocess (`bun --no-addons --no-install
  * --smol eval-child.ts <project>`): imports the project's `song.ts`, fills
- * sample hashes, and prints one JSON line. Never imported by dawg itself.
+ * sample hashes and Scala tuning files, and prints one JSON line. Never
+ * imported by dawg itself.
  */
 
 import { createHash } from "node:crypto";
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync, statSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { readTuningFiles } from "../tuning.ts";
 
 const MAX_SAMPLE_FILE_BYTES = 50 * 1024 * 1024;
+const MAX_TUNING_FILE_BYTES = 1024 * 1024;
 
 type Diagnostic = {
   message: string;
@@ -30,7 +33,10 @@ async function main(): Promise<void> {
     const song = module.default;
     if (typeof song !== "object" || song === null)
       throw new Error("song.ts must `export default song({...})`");
-    output = { ok: true, score: await withSampleHashes(song, project) };
+    output = {
+      ok: true,
+      score: withTuningFiles(await withSampleHashes(song, project), project),
+    };
   } catch (error) {
     output = { ok: false, error: diagnostic(error, project) };
   }
@@ -122,4 +128,33 @@ async function withSampleHashes(
   return plain;
 }
 
+/**
+ * Reads the Scala `.scl` and `.kbm` files a song or track tuning names, so
+ * the score carries the resolved table and renders without file access.
+ */
+function withTuningFiles(score: unknown, project: string): unknown {
+  if (typeof score !== "object" || score === null) return score;
+  const plain = score as Record<string, unknown>;
+  const read = (path: string): string | undefined => {
+    const file = resolve(project, path);
+    if (relative(project, file).startsWith("..")) return undefined;
+    try {
+      const info = statSync(file);
+      if (!info.isFile() || info.size > MAX_TUNING_FILE_BYTES) return undefined;
+      return readFileSync(file, "utf8");
+    } catch {
+      return undefined;
+    }
+  };
+  if (plain.tuning) plain.tuning = readTuningFiles(plain.tuning, read, "song");
+  for (const track of Array.isArray(plain.tracks) ? plain.tracks : [])
+    if (typeof track === "object" && track !== null && track.tuning)
+      track.tuning = readTuningFiles(
+        track.tuning,
+        read,
+        `track ${String(track.name ?? track.id)}`,
+      );
+  return plain;
+}
+
 await main();

package/core/sdk/print.ts

@@ -8,8 +8,10 @@
  */
 
 import { DRUM_VOICES, isDrumInstrument } from "../drums.ts";
+import { DEFAULT_FIXED_VELOCITY } from "../expression.ts";
 import type { RhythmRow } from "../euclid.ts";
 import { FX_LANES, fxSpec, type FxName, type FxValues } from "../fx.ts";
+import { MASTER_SPECS, MASTER_UNITS, type SongMaster } from "../master.ts";
 import { midiToPitch } from "../pitch.ts";
 import { rhythmVoicePitch, rowInSync } from "../rhythm.ts";
 import {
@@ -23,12 +25,16 @@ import {
   type WavetableParam,
   TrackScore,
   type AutomationPoint,
+  type FormEntry,
   type Note,
   type SampleRef,
   type Sampler,
+  type Section,
   type Track,
 } from "../score.ts";
 import { trackSlug } from "../slug.ts";
+import { barStartTick } from "../tempo.ts";
+import type { Tuning } from "../tuning.ts";
 import { DEFAULT_HIT_LENGTH, DEFAULT_VELOCITY } from "./v1.ts";
 
 const WIDTH = 80;
@@ -147,7 +153,12 @@ export function trackIdentifiers(
   const out = new Map<string, string>();
   for (const track of score.tracks) {
     let base = dirs.get(track.id)!.replace(/-/g, "_");
-    if (!/^[a-z_]/.test(base) || RESERVED.has(base)) base = `track_${base}`;
+    if (
+      !/^[a-z_]/.test(base) ||
+      RESERVED.has(base) ||
+      (score.time && TIME_HELPERS.includes(base))
+    )
+      base = `track_${base}`;
     let name = base;
     for (let n = 2; used.has(name); n += 1) name = `${base}_${n}`;
     used.add(name);
@@ -162,7 +173,12 @@ export function printSong(
   dirs: ReadonlyMap<string, string> = trackDirectories(score),
 ): string {
   const ids = trackIdentifiers(score, dirs);
-  const lines: string[] = ['import { song } from "dawg";'];
+  const time = printTime(score);
+  const helpers = [
+    "song",
+    ...TIME_HELPERS.filter((name) => time.used.has(name)),
+  ];
+  const lines: string[] = [`import { ${helpers.join(", ")} } from "dawg";`];
   for (const track of score.tracks)
     lines.push(
       `import ${ids.get(track.id)!} from "./tracks/${dirs.get(track.id)!}/track.ts";`,
@@ -174,8 +190,14 @@ export function printSong(
     `bars: ${num(score.bars)}`,
   ];
   if (score.key !== null) entries.push(`key: ${str(score.key)}`);
+  if (score.tuning)
+    entries.push(
+      `tuning: ${printTuning(score.tuning, INDENT, "tuning: ".length)}`,
+    );
   if (score.ticksPerBeat !== 480)
     entries.push(`ticksPerBeat: ${num(score.ticksPerBeat)}`);
+  if (time.marks.length > 0)
+    entries.push(`time: ${list(time.marks, INDENT, "time: ".length, 1)}`);
   entries.push(
     `tracks: ${list(
       score.tracks.map((track) => ids.get(track.id)!),
@@ -184,12 +206,150 @@ export function printSong(
       1,
     )}`,
   );
+  if (score.master) entries.push(printMaster(score.master));
+  // Song sections and form (0.5): printed only when the song has them.
+  if (score.sections.length > 0)
+    entries.push(
+      `sections: ${list(
+        score.sections.map((section) => printSection(section, INDENT + INDENT)),
+        INDENT,
+        "sections: ".length,
+        1,
+      )}`,
+    );
+  if (score.form.length > 0)
+    entries.push(`form: ${printForm(score.form, INDENT)}`);
+  if (score.loopSection !== undefined)
+    entries.push(`loopSection: ${str(score.loopSection)}`);
   lines.push("export default song({");
   for (const entry of entries) lines.push(`${INDENT}${entry},`);
   lines.push("});", "");
   return lines.join("\n");
 }
 
+/** SDK time helpers `song.ts` may import, in import order. */
+const TIME_HELPERS: readonly string[] = ["tempo", "ramp", "meter", "fermata"];
+
+/** `song({ time })` marks for a score's tempo map, meters and fermatas. */
+function printTime(score: TrackScore): {
+  marks: string[];
+  used: Set<string>;
+} {
+  const marks: string[] = [];
+  const used = new Set<string>();
+  const time = score.time;
+  if (!time) return { marks, used };
+  const beat = (tick: number) => num(tick / score.ticksPerBeat);
+  type Mark = { tick: number; order: number; text: string };
+  const all: Mark[] = [];
+  for (const event of time.tempo ?? []) {
+    if (event.ramp) {
+      used.add("ramp");
+      const curve = event.ramp === "exp" ? ', "exp"' : "";
+      all.push({
+        tick: event.tick,
+        order: 1,
+        text: `ramp(${beat(event.tick)}, ${num(event.bpm)}${curve})`,
+      });
+    } else {
+      used.add("tempo");
+      all.push({
+        tick: event.tick,
+        order: 1,
+        text: `tempo(${beat(event.tick)}, ${num(event.bpm)})`,
+      });
+    }
+  }
+  for (const change of time.meter ?? []) {
+    used.add("meter");
+    const tick = barStartTick(score, change.bar);
+    const unit = change.beatUnit ?? 4;
+    const value =
+      unit === 4
+        ? num(change.beatsPerBar)
+        : `[${num(change.beatsPerBar)}, ${num(unit)}]`;
+    all.push({ tick, order: 0, text: `meter(${beat(tick)}, ${value})` });
+  }
+  for (const hold of time.fermatas ?? []) {
+    used.add("fermata");
+    all.push({
+      tick: hold.tick,
+      order: 2,
+      text: `fermata(${beat(hold.tick)}, ${num(hold.beats)})`,
+    });
+  }
+  all.sort((a, b) => a.tick - b.tick || a.order - b.order);
+  for (const mark of all) marks.push(mark.text);
+  return { marks, used };
+}
+
+/**
+ * One `sections` item: `{ name: "verse", startBar: 0, bars: 8 }`. `indent`
+ * is the item's own line; expanded fields sit one level deeper.
+ */
+function printSection(section: Section, indent: string): string {
+  const inner = indent + INDENT;
+  const entries: (readonly [string, string])[] = [
+    ["name", str(section.name)],
+    ["startBar", num(section.startBar)],
+    ["bars", num(section.bars)],
+  ];
+  if (section.mute && section.mute.length > 0)
+    entries.push([
+      "mute",
+      list(section.mute.map(str), inner, "mute: ".length, 1),
+    ]);
+  if (section.vary) {
+    const vary = Object.entries(section.vary).map(([id, change]) => {
+      const key = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(id) ? id : str(id);
+      const fields: (readonly [string, string])[] = [];
+      if (change.transpose !== undefined)
+        fields.push(["transpose", num(change.transpose)]);
+      if (change.gain !== undefined) fields.push(["gain", num(change.gain)]);
+      return [key, obj(fields, inner + INDENT, `${key}: `.length, 1)] as const;
+    });
+    if (vary.length > 0)
+      entries.push(["vary", obj(vary, inner, "vary: ".length, 1)]);
+  }
+  return obj(entries, indent, 0, 1);
+}
+
+/**
+ * The form as a string when every name is plain (`"intro verse chorus*2"`),
+ * else as a list of entries.
+ */
+function printForm(form: readonly FormEntry[], indent: string): string {
+  // Word characters only, so the string reads back as the same entries.
+  const plain = form.every((entry) => /^\w+$/u.test(entry.section));
+  if (plain) {
+    const text = form
+      .map(
+        (entry) =>
+          `${entry.section}${(entry.repeat ?? 1) > 1 ? `*${entry.repeat}` : ""}`,
+      )
+      .join(" ");
+    return str(text);
+  }
+  return list(
+    form.map((entry) =>
+      (entry.repeat ?? 1) > 1
+        ? obj(
+            [
+              ["section", str(entry.section)],
+              ["repeat", num(entry.repeat!)],
+            ],
+            indent + INDENT,
+            0,
+            1,
+          )
+        : str(entry.section),
+    ),
+    indent,
+    "form: ".length,
+    1,
+  );
+}
+
 /** `tracks/<slug>/track.ts` for one track of a score. */
 export function printTrack(score: TrackScore, track: Track): string {
   // Rows whose lane still matches their expansion print as generators and
@@ -213,13 +373,13 @@ export function printTrack(score: TrackScore, track: Track): string {
   if (slots) for (const [voice, slot] of slots) voiceFor.set(slot, voice);
   const used = new Set<string>(["track"]);
   const printed = notes.map((note) => {
-    const voice = voiceFor.get(note.pitch);
+    const voice = note.cents ? undefined : voiceFor.get(note.pitch);
     if (voice !== undefined) {
       used.add("hit");
-      return printHit(score, note, voice);
+      return printHit(score, note, voice, INDENT + INDENT);
     }
     used.add("note");
-    return printNote(score, note, !kit && !slots);
+    return printNote(score, note, !kit && !slots, INDENT + INDENT);
   });
   if (track.sampler) used.add("sampler");
   const wavetable = isWavetableInstrument(track.instrument)
@@ -237,6 +397,28 @@ export function printTrack(score: TrackScore, track: Track): string {
     entries.push(`instrument: ${printWavetable(wavetable, INDENT)}`);
   } else entries.push(`instrument: ${str(track.instrument)}`);
   if (track.kit) entries.push(`kit: ${str(track.kit)}`);
+  if (track.time) {
+    const beats = (ticks: number) => num(ticks / score.ticksPerBeat);
+    const fields: (readonly [string, string])[] = [];
+    if (track.time.rate !== undefined)
+      fields.push(["rate", num(track.time.rate)]);
+    if (track.time.phase !== undefined)
+      fields.push(["phase", beats(track.time.phase)]);
+    if (track.time.cycle !== undefined)
+      fields.push(["cycle", beats(track.time.cycle)]);
+    if (track.time.steps) {
+      const { shift, hold, drift } = track.time.steps;
+      fields.push([
+        "steps",
+        `{ shift: ${beats(shift)}, hold: ${num(hold)}, drift: ${num(drift)} }`,
+      ]);
+    }
+    entries.push(`time: ${obj(fields, INDENT, "time: ".length, 1)}`);
+  }
+  if (track.tuning)
+    entries.push(
+      `tuning: ${printTuning(track.tuning, INDENT, "tuning: ".length)}`,
+    );
   if (track.muted) entries.push("muted: true");
   if (track.solo) entries.push("solo: true");
   if (track.volume !== 1) entries.push(`volume: ${num(track.volume)}`);
@@ -324,6 +506,7 @@ export function printTrack(score: TrackScore, track: Track): string {
     );
     entries.push(`synth: ${obj(params, INDENT, "synth: ".length, 1)}`);
   }
+  entries.push(...performanceEntries(score, track));
   const lanes: [string, readonly AutomationPoint[] | undefined][] = [
     ["volume", track.volumeAutomation],
     ["pan", track.panAutomation],
@@ -407,23 +590,185 @@ export function printTrack(score: TrackScore, track: Track): string {
   return lines.join("\n");
 }
 
-function printNote(score: TrackScore, note: Note, named: boolean): string {
-  const pitch = named ? str(midiToPitch(note.pitch)) : num(note.pitch);
+function printNote(
+  score: TrackScore,
+  note: Note,
+  named: boolean,
+  indent: string,
+): string {
+  // A detuned note always prints by name: `"E4-14c"`.
+  const pitch = note.cents
+    ? str(
+        `${midiToPitch(note.pitch)}${note.cents > 0 ? "+" : ""}${num(note.cents)}c`,
+      )
+    : named
+      ? str(midiToPitch(note.pitch))
+      : num(note.pitch);
   const args = [pitch, num(note.startTick / score.ticksPerBeat)];
   const length = note.durationTicks / score.ticksPerBeat;
-  if (length !== 1 || note.velocity !== DEFAULT_VELOCITY)
+  const how = expressionEntries(note, indent + INDENT);
+  if (length !== 1 || note.velocity !== DEFAULT_VELOCITY || how)
     args.push(num(length));
-  if (note.velocity !== DEFAULT_VELOCITY) args.push(num(note.velocity));
-  return `note(${args.join(", ")})`;
+  if (note.velocity !== DEFAULT_VELOCITY || how) args.push(num(note.velocity));
+  return call("note", args, how, indent);
 }
 
-function printHit(score: TrackScore, note: Note, voice: string): string {
+function printHit(
+  score: TrackScore,
+  note: Note,
+  voice: string,
+  indent: string,
+): string {
   const args = [str(voice), num(note.startTick / score.ticksPerBeat)];
   const length = note.durationTicks / score.ticksPerBeat;
-  if (note.velocity !== DEFAULT_VELOCITY || length !== DEFAULT_HIT_LENGTH)
+  const how = expressionEntries(note, indent + INDENT);
+  if (
+    note.velocity !== DEFAULT_VELOCITY ||
+    length !== DEFAULT_HIT_LENGTH ||
+    how
+  )
     args.push(num(note.velocity));
-  if (length !== DEFAULT_HIT_LENGTH) args.push(num(length));
-  return `hit(${args.join(", ")})`;
+  if (length !== DEFAULT_HIT_LENGTH || how) args.push(num(length));
+  return call("hit", args, how, indent);
+}
+
+/**
+ * A note's expression as the fields of its `how` argument, values laid out
+ * for property lines at `indent`; undefined when it has none.
+ */
+function expressionEntries(
+  note: Note,
+  indent: string,
+): (readonly [string, string])[] | undefined {
+  const entries: (readonly [string, string])[] = [];
+  if (note.articulation) entries.push(["art", str(note.articulation)]);
+  if (note.glide !== undefined) entries.push(["glide", num(note.glide)]);
+  if (note.bend) {
+    const points = note.bend.map((p) => `[${num(p.at)}, ${num(p.cents)}]`);
+    // Prettier forces a break on arrays of 2+ arrays that each hold 2+ items.
+    entries.push([
+      "bend",
+      list(points, indent, "bend: ".length, 1, points.length > 1),
+    ]);
+  }
+  if (note.vibrato)
+    entries.push([
+      "vibrato",
+      obj(
+        [
+          ["rate", num(note.vibrato.rate)],
+          ["depth", num(note.vibrato.depth)],
+          ...(note.vibrato.delay !== undefined
+            ? ([["delay", num(note.vibrato.delay)]] as const)
+            : []),
+        ],
+        indent,
+        "vibrato: ".length,
+        1,
+      ),
+    ]);
+  if (note.humanize) {
+    const { timing, velocity, length } = note.humanize;
+    entries.push([
+      "humanize",
+      obj(
+        [
+          ...(timing !== undefined ? ([["timing", num(timing)]] as const) : []),
+          ...(velocity !== undefined
+            ? ([["velocity", num(velocity)]] as const)
+            : []),
+          ...(length !== undefined ? ([["length", num(length)]] as const) : []),
+        ],
+        indent,
+        "humanize: ".length,
+        1,
+      ),
+    ]);
+  }
+  return entries.length === 0 ? undefined : entries;
+}
+
+/**
+ * `name(args, how)` as a list item at `indent`: on one line when it fits,
+ * otherwise with the trailing `how` object hugged and broken one field per
+ * line, the way prettier prints a last object argument.
+ */
+function call(
+  name: string,
+  args: readonly string[],
+  how: readonly (readonly [string, string])[] | undefined,
+  indent: string,
+): string {
+  if (!how) return `${name}(${args.join(", ")})`;
+  const inline = `${name}(${[...args, `{ ${how.map(([k, v]) => `${k}: ${v}`).join(", ")} }`].join(", ")})`;
+  if (!inline.includes("\n") && indent.length + inline.length + 1 <= WIDTH)
+    return inline;
+  const inner = indent + INDENT;
+  const body = how.map(([k, v]) => property(k, v, inner)).join("\n");
+  return `${name}(${[...args, "{"].join(", ")}\n${body}\n${indent}})`;
+}
+
+/** A track's performance fields (SDK 1.15.0) as `key: literal` entries. */
+function performanceEntries(score: TrackScore, track: Track): string[] {
+  const entries: string[] = [];
+  if (track.glide)
+    entries.push(
+      track.glide.mode === "legato"
+        ? `glide: ${num(track.glide.time)}`
+        : `glide: ${obj(
+            [
+              ["time", num(track.glide.time)],
+              ["mode", str(track.glide.mode)],
+            ],
+            INDENT,
+            "glide: ".length,
+            1,
+          )}`,
+    );
+  if (track.pedal) {
+    const events = track.pedal.map(
+      (event) =>
+        `[${num(event.tick / score.ticksPerBeat)}, ${str(event.state)}]`,
+    );
+    entries.push(
+      `pedal: ${list(events, INDENT, "pedal: ".length, 1, events.length > 1)}`,
+    );
+  }
+  if (track.velocityCurve)
+    entries.push(
+      track.velocityCurve.curve !== "fixed" ||
+        (track.velocityCurve.fixed ?? DEFAULT_FIXED_VELOCITY) ===
+          DEFAULT_FIXED_VELOCITY
+        ? `velocityCurve: ${str(track.velocityCurve.curve)}`
+        : `velocityCurve: ${obj(
+            [
+              ["curve", str(track.velocityCurve.curve)],
+              ["fixed", num(track.velocityCurve.fixed!)],
+            ],
+            INDENT,
+            "velocityCurve: ".length,
+            1,
+          )}`,
+    );
+  if (track.humanize) {
+    const { timing, velocity, length, seed } = track.humanize;
+    entries.push(
+      `humanize: ${obj(
+        [
+          ...(timing !== undefined ? ([["timing", num(timing)]] as const) : []),
+          ...(velocity !== undefined
+            ? ([["velocity", num(velocity)]] as const)
+            : []),
+          ...(length !== undefined ? ([["length", num(length)]] as const) : []),
+          ["seed", num(seed)],
+        ],
+        INDENT,
+        "humanize: ".length,
+        1,
+      )}`,
+    );
+  }
+  return entries;
 }
 
 /** `euclid("hat", 7, 16, 2, { velocity: 0.5 })` or `grid("sd", "....x...")`. */
@@ -574,6 +919,92 @@ function printSample(ref: SampleRef, indent: string, prefix: number): string {
   return obj(entries, indent, prefix, 1);
 }
 
+/**
+ * A song or track tuning: a bare library name, or an object without the
+ * fields dawg resolved from Scala files (the table of an `scl`, the keymap
+ * of a `kbm`).
+ */
+function printTuning(tuning: Tuning, indent: string, prefix: number): string {
+  const entries: [string, string][] = [];
+  if (tuning.name !== undefined) entries.push(["name", str(tuning.name)]);
+  if (tuning.scl === undefined) {
+    const inner = indent + INDENT;
+    if (tuning.edo !== undefined) entries.push(["edo", num(tuning.edo)]);
+    if (tuning.ratios)
+      entries.push([
+        "ratios",
+        list(tuning.ratios.map(str), inner, "ratios: ".length, 1),
+      ]);
+    if (tuning.cents)
+      entries.push([
+        "cents",
+        fill(tuning.cents.map(num), inner, "cents: ".length, 1),
+      ]);
+  } else entries.push(["scl", str(tuning.scl)]);
+  if (tuning.kbm !== undefined) entries.push(["kbm", str(tuning.kbm)]);
+  if (tuning.ref !== undefined) entries.push(["ref", num(tuning.ref)]);
+  if (tuning.root !== undefined)
+    entries.push(["root", str(midiToPitch(tuning.root))]);
+  if (tuning.map !== undefined) entries.push(["map", str(tuning.map)]);
+  if (entries.length === 1 && entries[0]![0] === "name") return entries[0]![1];
+  return obj(entries, indent, prefix, 1);
+}
+
+/**
+ * Number array the way prettier prints one: inline when it fits, else
+ * filled (as many per line as fit, each followed by a comma).
+ */
+function fill(
+  items: readonly string[],
+  indent: string,
+  prefix: number,
+  trailing: number,
+): string {
+  const inline = `[${items.join(", ")}]`;
+  if (
+    items.length < 2 ||
+    indent.length + prefix + inline.length + trailing <= WIDTH
+  )
+    return inline;
+  const inner = indent + INDENT;
+  const lines: string[] = [];
+  let line = "";
+  for (const item of items) {
+    const next = `${item},`;
+    if (line !== "" && inner.length + line.length + 1 + next.length <= WIDTH)
+      line += ` ${next}`;
+    else {
+      if (line !== "") lines.push(inner + line);
+      line = next;
+    }
+  }
+  lines.push(inner + line);
+  return `[\n${lines.join("\n")}\n${indent}]`;
+}
+
+/** `master: { … }`, always expanded like `fx`; units in chain order. */
+function printMaster(master: SongMaster): string {
+  const inner = INDENT + INDENT;
+  const body: string[] = [];
+  for (const unit of MASTER_UNITS) {
+    const values = master[unit];
+    if (!values) continue;
+    // Only values that differ from the default: loading fills the rest.
+    const params = Object.entries(MASTER_SPECS[unit].params)
+      .filter(
+        ([key, spec]) =>
+          values[key] !== undefined && values[key] !== spec.default,
+      )
+      .map(([key]) => [key, value(values[key]!)] as const);
+    body.push(
+      `${inner}${unit}: ${params.length === 0 ? "{}" : obj(params, inner, `${unit}: `.length, 1)},`,
+    );
+  }
+  if (master.target !== undefined)
+    body.push(`${inner}target: ${num(master.target)},`);
+  return `master: {\n${body.join("\n")}\n${INDENT}}`;
+}
+
 /** Object literal: inline when the line fits, expanded otherwise (prettier keeps both). */
 function obj(
   entries: readonly (readonly [string, string])[],