@hraness/dawg 0.6.1 → 0.7.0

package/core/keys.ts

@@ -57,15 +57,15 @@ export function isElectricFamily(
 
 /**
  * Why una corda would not sound on this track (0.6.1), or undefined when it
- * does: only the modelled pianos with a `keys` object read `softPedal`.
+ * does: only the modeled pianos with a `keys` object read `softPedal`.
  */
 export function softPedalNote(
   track: Readonly<{ id: string; instrument: string; keys?: unknown }>,
 ): string | undefined {
   if (!isPianoFamily(track.instrument))
-    return `${track.id} is ${track.instrument}; una corda acts on the modelled pianos (${PIANO_FAMILIES.join(" ")})`;
+    return `${track.id} is ${track.instrument}; una corda acts on the modeled pianos (${PIANO_FAMILIES.join(" ")})`;
   if (track.keys === undefined)
-    return `${track.id} has no modelled piano yet; keys preset ${track.instrument} first`;
+    return `${track.id} has no modeled piano yet; keys preset ${track.instrument} first`;
   return undefined;
 }
 

package/core/loop.ts

@@ -10,6 +10,7 @@ import {
   type Track,
 } from "./score.ts";
 import type { SongMaster } from "./master.ts";
+import type { SongStyle } from "./style-provenance.ts";
 import type { Tuning } from "./tuning.ts";
 
 export const LOOP_FORMAT = "track.loop/v1" as const;
@@ -30,6 +31,8 @@ export type TrackLoopV1 = Readonly<{
   notes: readonly Note[];
   /** Song master (dawg 0.5); absent means none. */
   master?: SongMaster;
+  /** Which style and seed made the song (quality-08); absent means none. */
+  style?: SongStyle;
   /** Song sections (0.5); omitted when the song has none. */
   sections?: readonly Section[];
   /** Song form (0.5); omitted when empty. */
@@ -53,11 +56,13 @@ export function encodeLoopDocument(score: TrackScore): TrackLoopV1 {
     tracks: score.tracks,
     notes: score.notes,
     ...(score.master ? { master: score.master } : {}),
+    ...(score.style ? { style: score.style } : {}),
     ...(score.sections.length > 0 ? { sections: score.sections } : {}),
     ...(score.form.length > 0 ? { form: score.form } : {}),
     ...(score.loopSection === undefined
       ? {}
       : { loopSection: score.loopSection }),
+    ...(score.calibration ? { calibration: score.calibration } : {}),
   });
 }
 

package/core/lyrics.ts

@@ -0,0 +1,297 @@
+/**
+ * The lyric grammar and syllable assignment (0.7) shared by `/lyrics`,
+ * `set_lyrics` and the SDK's `lyrics()`. No imports: the SDK carries a copy
+ * between marker lines (`bun core/sdk/sync-lyrics.ts`).
+ */
+
+// ---- lyrics (copied into core/sdk/v1.ts)
+
+/** Longest lyric on one note (SCORE_LIMITS.maxLyricLength). */
+export const LYRIC_LIMIT = 32;
+
+/** One lyric token: a syllable, a held note (`_`) or a skipped note (`~`). */
+export type LyricToken = Readonly<{
+  syl: string;
+  /** Index of the word the token belongs to. */
+  word: number;
+  /** First syllable of its word. */
+  first: boolean;
+  kind: "syl" | "hold" | "rest";
+}>;
+
+/**
+ * The lyric grammar: words split by spaces, syllables by `-`, `_` holds the
+ * previous syllable over the next note (melisma), `~` skips a note.
+ * "sun-lit morn-ing _ glow" gives sun lit morn ing _ glow.
+ */
+export function parseLyric(text: string): LyricToken[] {
+  const out: LyricToken[] = [];
+  let word = -1;
+  for (const raw of text.trim().split(/\s+/u)) {
+    if (raw === "") continue;
+    if (raw === "_") out.push({ syl: "_", word, first: false, kind: "hold" });
+    else if (raw === "~")
+      out.push({ syl: "~", word, first: false, kind: "rest" });
+    else {
+      word += 1;
+      raw
+        .split("-")
+        .filter(Boolean)
+        .forEach((syl, index) =>
+          out.push({ syl, word, first: index === 0, kind: "syl" }),
+        );
+    }
+  }
+  return out;
+}
+
+const VOWEL = /[aeiouàáâäèéêëìíîïòóôöùúûü]/u;
+/** Consonant pairs that sound as one consonant and are never split. */
+const SYL_DIGRAPHS = new Set(["th", "sh", "ch", "ph", "wh", "ng", "ck", "gh"]);
+/** Digraphs that end a syllable (no English word starts with them). */
+const SYL_CODA_ONLY = new Set(["ng", "ck", "gh", "x"]);
+/** Consonant clusters a syllable may start with (maximal onset). */
+const SYL_ONSETS = new Set(
+  (
+    "bl br cl cr dr fl fr gl gr pl pr sc sk sl sm sn sp st sw tr tw dw " +
+    "thr shr chr phr phl spl spr str scr squ skr"
+  ).split(" "),
+);
+/** Common words ending in a silent `e` that start compounds (some-thing). */
+const SYL_SILENT_E_HEADS = (
+  "some home life time love fire side care where there here more one " +
+  "make lone like name game base wide grace face place space stone bone"
+).split(" ");
+/** Suffixes kept whole after a silent `e` (love-ly, care-ful). */
+const SYL_SUFFIXES = ["ly", "ful", "less", "ness", "ment"];
+/** Unstressed endings that close a short vowel before them (nev-er). */
+const SYL_CLOSING_ENDINGS = new Set([
+  "er",
+  "en",
+  "el",
+  "et",
+  "ed",
+  "es",
+  "est",
+  "ing",
+]);
+
+/**
+ * Syllables of a word typed without hyphens: a guess for English, which a
+ * hyphen always overrides (`nev-er`). Each run of vowels (and `y` after a
+ * consonant) is one syllable; a final silent `e` does not count, but a
+ * consonant plus `le` is its own syllable (lit-tle, ta-ble). Consonant
+ * pairs that sound as one (th sh ch ph wh ng ck gh) never split. Between
+ * vowels a cluster gives the next syllable the longest onset English
+ * allows (mon-ster, chil-dren); one consonant goes with the next vowel
+ * (ba-by, to-night) unless the previous vowel is short before an
+ * unstressed ending (nev-er, sing-ing). "something" gives some thing,
+ * "forever" for ev er.
+ */
+export function autoSyllabify(word: string): string[] {
+  const w = word.toLowerCase();
+  // Compounds and suffixes after a silent e: some-thing, love-ly.
+  if (w.length >= 6) {
+    for (const head of SYL_SILENT_E_HEADS)
+      if (w.startsWith(head) && VOWEL.test(w.slice(head.length)))
+        return [
+          word.slice(0, head.length),
+          ...autoSyllabify(word.slice(head.length)),
+        ];
+    for (const suffix of SYL_SUFFIXES) {
+      const stem = w.slice(0, -suffix.length);
+      if (
+        w.endsWith(suffix) &&
+        stem.length >= 3 &&
+        stem.endsWith("e") &&
+        !VOWEL.test(stem[stem.length - 2]!)
+      )
+        return [
+          ...autoSyllabify(word.slice(0, stem.length)),
+          word.slice(stem.length),
+        ];
+    }
+  }
+  // Letters into units: a vowel, a consonant, a digraph, or `qu`.
+  type Unit = { at: number; text: string; vowel: boolean };
+  const units: Unit[] = [];
+  for (let i = 0; i < w.length;) {
+    const pair = w.slice(i, i + 2);
+    if (pair === "qu" || SYL_DIGRAPHS.has(pair)) {
+      units.push({ at: i, text: pair, vowel: false });
+      i += 2;
+      continue;
+    }
+    const ch = w[i]!;
+    const prev = units.at(-1);
+    const vowel =
+      VOWEL.test(ch) || (ch === "y" && prev !== undefined && !prev.vowel);
+    units.push({ at: i, text: ch, vowel });
+    i += 1;
+  }
+  // Vowel groups as [first unit, last unit].
+  const groups: [number, number][] = [];
+  for (let u = 0; u < units.length;) {
+    if (units[u]!.vowel) {
+      let v = u;
+      while (v + 1 < units.length && units[v + 1]!.vowel) v += 1;
+      groups.push([u, v]);
+      u = v + 1;
+    } else u += 1;
+  }
+  const lastUnit = units.length - 1;
+  const finalLe =
+    w.endsWith("le") &&
+    units.length >= 3 &&
+    units[lastUnit - 1]!.text === "l" &&
+    !units[lastUnit - 2]!.vowel;
+  const last = groups.at(-1);
+  if (
+    groups.length > 1 &&
+    last &&
+    last[0] === lastUnit &&
+    last[1] === lastUnit &&
+    units[lastUnit]!.text === "e" &&
+    !units[lastUnit - 1]!.vowel &&
+    !finalLe
+  )
+    groups.pop();
+  if (groups.length <= 1) return [word];
+  const cuts: number[] = [];
+  for (let g = 1; g < groups.length; g += 1) {
+    const prev = groups[g - 1]!;
+    const next = groups[g]!;
+    const cluster = units.slice(prev[1] + 1, next[0]);
+    const n = cluster.length;
+    const isLast = g === groups.length - 1;
+    let onset: number; // units of the cluster that start the next syllable
+    if (isLast && finalLe && n >= 2)
+      onset = cluster[n - 2]!.text === "ck" ? 1 : 2;
+    else if (n === 1) {
+      const unit = cluster[0]!.text;
+      const prevText = units
+        .slice(prev[0], prev[1] + 1)
+        .map((u) => u.text)
+        .join("");
+      const ending = w.slice(units[next[0]]!.at);
+      const short = prevText.length === 1 && "eiou".includes(prevText);
+      const closes =
+        SYL_CODA_ONLY.has(unit) ||
+        (short && isLast && SYL_CLOSING_ENDINGS.has(ending)) ||
+        (unit === "r" && short && units[next[0]]!.text === "e");
+      onset = closes ? 0 : 1;
+    } else {
+      onset = 1;
+      for (let k = n - 1; k >= 2; k -= 1)
+        if (
+          SYL_ONSETS.has(
+            cluster
+              .slice(n - k)
+              .map((u) => u.text)
+              .join(""),
+          )
+        ) {
+          onset = k;
+          break;
+        }
+      if (SYL_CODA_ONLY.has(cluster[n - 1]!.text)) onset = 0;
+    }
+    const first = units[next[0] - onset]!;
+    cuts.push(onset === 0 ? units[next[0]]!.at : first.at);
+  }
+  const out: string[] = [];
+  let at = 0;
+  for (const cut of cuts) {
+    out.push(word.slice(at, cut));
+    at = cut;
+  }
+  out.push(word.slice(at));
+  return out.filter(Boolean);
+}
+
+/** What `assignLyrics` put on each note, and what did not fit. */
+export type LyricAssignment = Readonly<{
+  /** Note id to its lyric (`_` holds); notes `~` skipped are absent. */
+  lyrics: ReadonlyMap<string, string>;
+  /** Syllables left over after the last note. */
+  dropped: readonly string[];
+  /** Words split automatically. */
+  split: readonly string[];
+}>;
+
+/**
+ * Lyrics onto `notes` in time order. Hyphens split syllables as typed;
+ * when the text has fewer syllables than there are notes, words typed
+ * whole are split by `autoSyllabify`, and any notes still left hold the
+ * last syllable (melisma) instead of failing. Syllables past the last note
+ * are reported in `dropped`. Notes sharing an onset take one token, on
+ * the top note, with `_` on the others. Each lyric is cut to the 32-character limit.
+ */
+export function assignLyrics(
+  text: string,
+  notes: readonly Readonly<{ id: string; startTick: number; pitch: number }>[],
+): LyricAssignment {
+  const sorted = [...notes].sort(
+    (a, b) => a.startTick - b.startTick || b.pitch - a.pitch,
+  );
+  // Notes sharing an onset (a chord or a doubled note) take one token: the
+  // top note carries it and the rest hold.
+  const ordered: (typeof sorted)[number][] = [];
+  const under = new Map<string, string[]>();
+  for (const note of sorted) {
+    const top = ordered.at(-1);
+    if (top && top.startTick === note.startTick)
+      under.get(top.id)!.push(note.id);
+    else {
+      ordered.push(note);
+      under.set(note.id, []);
+    }
+  }
+  let tokens = parseLyric(text);
+  const split: string[] = [];
+  if (tokens.length < ordered.length) {
+    // Split every word typed whole; keep the split only if it still fits.
+    const out: LyricToken[] = [];
+    const words: string[] = [];
+    for (const token of tokens) {
+      const whole =
+        token.kind === "syl" &&
+        token.first &&
+        !tokens.some((t) => t.word === token.word && !t.first);
+      if (!whole) {
+        out.push(token);
+        continue;
+      }
+      const parts = autoSyllabify(token.syl);
+      if (parts.length > 1) words.push(token.syl);
+      parts.forEach((syl, index) =>
+        out.push({ syl, word: token.word, first: index === 0, kind: "syl" }),
+      );
+    }
+    if (out.length <= ordered.length) {
+      tokens = out;
+      split.push(...words);
+    }
+  }
+  const lyrics = new Map<string, string>();
+  const limit = LYRIC_LIMIT;
+  ordered.forEach((note, index) => {
+    const token = tokens[index];
+    if (!token) {
+      if (tokens.length > 0)
+        for (const id of [note.id, ...under.get(note.id)!]) lyrics.set(id, "_");
+      return;
+    }
+    if (token.kind === "rest") return;
+    lyrics.set(
+      note.id,
+      token.kind === "hold" ? "_" : token.syl.slice(0, limit),
+    );
+    for (const id of under.get(note.id)!) lyrics.set(id, "_");
+  });
+  const dropped = tokens
+    .slice(ordered.length)
+    .filter((token) => token.kind === "syl")
+    .map((token) => token.syl);
+  return { lyrics, dropped, split };
+}

package/core/master.ts

@@ -105,10 +105,10 @@ export const MASTER_SPECS: Readonly<Record<MasterUnit, MasterUnitSpec>> =
         low: db(-12, 12, 0, "low shelf gain"),
         lowfreq: hz(20, 1000, 100, "low shelf corner"),
         bell1: db(-12, 12, 0, "first bell gain"),
-        bell1freq: hz(40, 16_000, 400, "first bell centre"),
+        bell1freq: hz(40, 16_000, 400, "first bell center"),
         bell1q: q("first bell width: higher is narrower"),
         bell2: db(-12, 12, 0, "second bell gain"),
-        bell2freq: hz(200, 18_000, 3_000, "second bell centre"),
+        bell2freq: hz(200, 18_000, 3_000, "second bell center"),
         bell2q: q("second bell width: higher is narrower"),
         high: db(-12, 12, 0, "high shelf gain"),
         highfreq: hz(1_000, 20_000, 10_000, "high shelf corner"),
@@ -222,7 +222,7 @@ export const MASTER_SPECS: Readonly<Record<MasterUnit, MasterUnitSpec>> =
           default: 120,
           step: 10,
           unit: "Hz",
-          doc: "below this the mix is mono (keeps bass centred); 0 is off",
+          doc: "below this the mix is mono (keeps bass centered); 0 is off",
         },
       },
     },

package/core/resonators.ts

@@ -19,6 +19,7 @@
  */
 import { resolveInstrumentWord } from "./instruments.ts";
 import { WIND_INSTRUMENT, windPresetFor, type TrackWind } from "./winds.ts";
+import { SING_INSTRUMENT, isSingPreset, type TrackSing } from "./sing.ts";
 import {
   FxValidationError,
   isRecord,
@@ -175,7 +176,7 @@ export const MODAL_PARAMS: Readonly<Record<string, ParamSpec>> = Object.freeze({
   hardness: num(0, 1, 0.4, 0.05, "mallet hardness: 0 yarn/felt, 1 brass", {
     automate: true,
   }),
-  position: num(0, 1, 0.42, 0.05, "strike point: 0 end or edge, 0.5 centre", {
+  position: num(0, 1, 0.42, 0.05, "strike point: 0 end or edge, 0.5 center", {
     automate: true,
   }),
   ring: num(0.05, 30, 1.6, "log", "ring time (T60) at middle C", {
@@ -768,8 +769,20 @@ export function instrumentPatchForWord(word: string): {
   instrument: string;
   modal?: TrackModal;
   wind?: TrackWind;
+  sing?: TrackSing;
 } {
   const meaning = resolveInstrumentWord(word);
+  // f07-sing: `choir`, `aah`, `khoomei` sing a preset.
+  if (meaning?.field === "sing" && meaning.instrument === SING_INSTRUMENT) {
+    const preset =
+      meaning.preset && isSingPreset(meaning.preset)
+        ? meaning.preset
+        : undefined;
+    return {
+      instrument: SING_INSTRUMENT,
+      sing: Object.freeze(preset ? { preset } : {}) as TrackSing,
+    };
+  }
   // f061-gamelan-winds: `flute`, `sax`, `tuba` play a wind preset.
   if (meaning?.field === "wind" && meaning.instrument === WIND_INSTRUMENT) {
     const preset = meaning.preset ? windPresetFor(meaning.preset) : undefined;
@@ -793,7 +806,8 @@ export function isModalWord(word: string): boolean {
   const meaning = resolveInstrumentWord(word);
   return (
     meaning?.instrument === MODAL_INSTRUMENT ||
-    (meaning?.field === "wind" && meaning.instrument === WIND_INSTRUMENT)
+    (meaning?.field === "wind" && meaning.instrument === WIND_INSTRUMENT) ||
+    (meaning?.field === "sing" && meaning.instrument === SING_INSTRUMENT)
   );
 }
 

package/core/routing.ts

@@ -0,0 +1,165 @@
+/**
+ * Cross-track references (0.7). A track field that names another track (the
+ * vocoder's `src`, autotune's `from`, 0.7.1 harmony's `guide`) registers
+ * here once, at module load, with the edges it reads and how it forgets a
+ * removed track. `removeTrack` then drops dangling references, the renderer
+ * orders stems with `routingOrder`, and stem digests include the notes a
+ * track follows through `notesDigestInputs`.
+ *
+ * Audio edges carry rendered sound (the target must render first, and a
+ * cycle is an error). Notes edges only read the other track's notes, so
+ * they never order rendering and never form a cycle.
+ */
+import {
+  registerTrackRefDrop,
+  ScoreValidationError,
+  type Note,
+  type Track,
+  type TrackScore,
+} from "./score.ts";
+import { trackSlug } from "./slug.ts";
+
+export type TrackRefKind = "audio" | "notes";
+
+/** One reference from a track to another track. */
+export type TrackRef = Readonly<{ trackId: string; kind: TrackRefKind }>;
+
+export type TrackRefSpec = Readonly<{
+  /** The tracks `track` references through this field. */
+  refs(track: Track): readonly TrackRef[];
+  /** `track` without its references to `removedId`. */
+  drop(track: Track, removedId: string): Track;
+}>;
+
+const specs = new Map<string, TrackRefSpec>();
+
+/** Registers a referencing field once; registering it again replaces it. */
+export function registerTrackRefs(field: string, spec: TrackRefSpec): void {
+  specs.set(field, spec);
+  registerTrackRefDrop(field, spec.drop);
+}
+
+/** Every reference `track` holds, in field registration order. */
+export function trackRefs(track: Track): readonly TrackRef[] {
+  const refs: TrackRef[] = [];
+  for (const spec of specs.values()) refs.push(...spec.refs(track));
+  return refs;
+}
+
+/**
+ * Finds a track by id, then by name slug (`Lead Vox` and `lead-vox` both
+ * match). Returns undefined when nothing matches.
+ */
+export function resolveTrackRef(
+  score: TrackScore,
+  idOrSlug: string,
+): Track | undefined {
+  const byId = score.tracks.find((track) => track.id === idOrSlug);
+  if (byId) return byId;
+  const slug = trackSlug(idOrSlug);
+  return score.tracks.find((track) => trackSlug(track.name) === slug);
+}
+
+/**
+ * Track ids in render order: every audio source before the tracks that
+ * read it, otherwise score order. References to missing tracks are ignored.
+ * A cycle throws a ScoreValidationError that names it (`a -> b -> a`).
+ */
+export function routingOrder(score: TrackScore): readonly string[] {
+  const ids = new Set(score.tracks.map((track) => track.id));
+  const sources = new Map<string, string[]>();
+  for (const track of score.tracks)
+    sources.set(
+      track.id,
+      trackRefs(track)
+        .filter((ref) => ref.kind === "audio" && ids.has(ref.trackId))
+        .map((ref) => ref.trackId),
+    );
+  const order: string[] = [];
+  const state = new Map<string, "visiting" | "done">();
+  const stack: string[] = [];
+  const visit = (id: string): void => {
+    const seen = state.get(id);
+    if (seen === "done") return;
+    if (seen === "visiting") {
+      const cycle = [...stack.slice(stack.indexOf(id)), id];
+      throw new ScoreValidationError(
+        `track routing has a cycle: ${cycle.join(" -> ")}`,
+        "routing-cycle",
+      );
+    }
+    state.set(id, "visiting");
+    stack.push(id);
+    for (const source of sources.get(id) ?? []) visit(source);
+    stack.pop();
+    state.set(id, "done");
+    order.push(id);
+  };
+  for (const track of score.tracks) visit(track.id);
+  return order;
+}
+
+/**
+ * The notes a track's render depends on through notes edges, by referenced
+ * track id (sorted, deduplicated), for its stem digest. Missing tracks and
+ * self references contribute nothing.
+ */
+export function notesDigestInputs(
+  score: TrackScore,
+  trackId: string,
+): readonly Readonly<{ trackId: string; notes: readonly Note[] }>[] {
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return [];
+  const ids = new Set(score.tracks.map((candidate) => candidate.id));
+  const followed = [
+    ...new Set(
+      trackRefs(track)
+        .filter(
+          (ref) =>
+            ref.kind === "notes" &&
+            ref.trackId !== trackId &&
+            ids.has(ref.trackId),
+        )
+        .map((ref) => ref.trackId),
+    ),
+  ].sort();
+  return followed.map((id) => ({
+    trackId: id,
+    notes: score.notes.filter((note) => note.trackId === id),
+  }));
+}
+
+/**
+ * The vocoder's modulator (0.7): `vocoder.src` is an audio edge, so the
+ * modulator renders first and removing it drops the `src` (the carrier then
+ * plays dry until a new source is set).
+ */
+registerTrackRefs("vocoder", {
+  refs: (track) =>
+    track.vocoder?.src !== undefined
+      ? [{ trackId: track.vocoder.src, kind: "audio" }]
+      : [],
+  drop: (track, removedId) => {
+    if (track.vocoder?.src !== removedId) return track;
+    const { src: _src, ...rest } = track.vocoder;
+    return { ...track, vocoder: rest };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Registered reference fields (one block per lane).
+
+// autotune: `Track.autotune.from` follows another track's notes.
+registerTrackRefs("autotune.from", {
+  refs: (track) =>
+    track.autotune?.from !== undefined
+      ? [{ trackId: track.autotune.from, kind: "notes" }]
+      : [],
+  drop: (track, removedId) => {
+    if (track.autotune?.from !== removedId) return track;
+    // Without its melody the track follows its own notes; `to` and the
+    // preset stay as the user set them.
+    const { from: _from, ...autotune } = track.autotune;
+    return { ...track, autotune };
+  },
+});