@libraz/libcantus 1.0.1 → 1.2.0

package/dist/{chunk-FVSI36UV.js → chunk-7KG3RTYS.js}

@@ -1,26 +1,16 @@
 import {
+  ARTICULATIONS,
+  BEAT_EPS,
   InvalidInputError,
   assertFiniteNumber,
   assertInteger,
+  assertMidiPitch,
   assertNoteEvents,
-  assertRange
-} from "./chunk-VTI6FOLB.js";
-
-// src/core/instrument/articulation.ts
-var ARTICULATIONS = Object.freeze([
-  "accent",
-  "ghost",
-  "staccato",
-  "legato",
-  "slide",
-  "hammer",
-  "mute",
-  "flam",
-  "drag",
-  "roll",
-  "choke",
-  "open"
-]);
+  assertOneOf,
+  assertPositiveInt,
+  assertRange,
+  describeRejected
+} from "./chunk-AGOVW7U6.js";
 
 // src/core/instrument/profile.ts
 var LIMBS = Object.freeze(["rightHand", "leftHand", "rightFoot", "leftFoot"]);
@@ -47,19 +37,55 @@ function toStringedProfile(value, name = "instrument") {
   }
   return profile;
 }
+var MAX_FRETS = 127;
+var MAX_POLYPHONY = 128;
 function assertProfile(profile) {
+  if (typeof profile.name !== "string" || profile.name === "") {
+    throw new InvalidInputError(
+      `instrument name must be a non-empty string; received ${describeRejected(profile.name)}`
+    );
+  }
+  if (!Array.isArray(profile.articulations)) {
+    throw new InvalidInputError(
+      `${profile.name} articulations must be an array; received ${describeRejected(profile.articulations)}`
+    );
+  }
+  for (const [index, articulation] of profile.articulations.entries()) {
+    assertOneOf(articulation, ARTICULATIONS, `${profile.name} articulations[${index}]`);
+  }
+  assertPositiveInt(profile.polyphony, `${profile.name} polyphony`, MAX_POLYPHONY);
   if (profile.kind === "stringed") {
-    if (profile.tuning.length === 0) {
+    if (!Array.isArray(profile.tuning) || profile.tuning.length === 0) {
       throw new InvalidInputError(`${profile.name} must have at least one string`);
     }
-    if (!Number.isInteger(profile.frets) || profile.frets < 0) {
-      throw new InvalidInputError(`${profile.name} frets must be a non-negative integer`);
+    for (const [index, open] of profile.tuning.entries()) {
+      assertMidiPitch(open, `${profile.name} tuning[${index}]`);
     }
+    assertInteger(profile.frets, `${profile.name} frets`, 0, MAX_FRETS);
+    assertInteger(profile.maxStretch, `${profile.name} maxStretch`, 0, MAX_FRETS);
     return;
   }
-  if (Object.keys(profile.reach).length === 0) {
+  if (!Array.isArray(profile.limbs) || profile.limbs.length === 0) {
+    throw new InvalidInputError(`${profile.name} must have at least one limb`);
+  }
+  for (const [index, limb] of profile.limbs.entries()) {
+    assertOneOf(limb, LIMBS, `${profile.name} limbs[${index}]`);
+  }
+  if (typeof profile.reach !== "object" || profile.reach === null) {
+    throw new InvalidInputError(
+      `${profile.name} reach must be a table of limbs by voice; received ${describeRejected(profile.reach)}`
+    );
+  }
+  const voices = Object.keys(profile.reach);
+  for (const key of voices) {
+    assertMidiPitch(Number(key), `${profile.name} reach pitch`);
+  }
+  if (voices.every((key) => reachOf(profile, Number(key)).length === 0)) {
     throw new InvalidInputError(`${profile.name} must have at least one voice within reach`);
   }
+  for (const pitch of profile.overdub ?? []) {
+    assertMidiPitch(pitch, `${profile.name} overdub pitch`);
+  }
 }
 function reachOf(profile, pitch) {
   if (pitch === void 0) {
@@ -68,7 +94,9 @@ function reachOf(profile, pitch) {
   return (profile.reach[pitch] ?? []).filter((limb) => profile.limbs.includes(limb));
 }
 function instrumentRange(profile) {
-  assertProfile(profile);
+  return rangeIn(toInstrumentProfile(profile));
+}
+function rangeIn(profile) {
   if (profile.kind === "stringed") {
     let low2 = Number.POSITIVE_INFINITY;
     let high2 = Number.NEGATIVE_INFINITY;
@@ -91,43 +119,56 @@ function instrumentRange(profile) {
   return { low, high };
 }
 function canSound(profile, pitch) {
-  assertProfile(profile);
+  const resolved = toInstrumentProfile(profile, "instrument");
+  assertMidiPitch(pitch, "pitch");
+  return soundsIn(resolved, pitch);
+}
+function soundsIn(profile, pitch) {
   if (profile.kind === "stringed") {
     return profile.tuning.some((open) => pitch >= open && pitch - open <= profile.frets);
   }
   return reachOf(profile, pitch).length > 0;
 }
 function fingeringsFor(profile, pitch) {
-  assertProfile(profile);
+  const stringed = toStringedProfile(profile, "instrument");
+  assertMidiPitch(pitch, "pitch");
+  return fingeringsIn(stringed, pitch);
+}
+function fingeringsIn(stringed, pitch) {
   const out = [];
-  for (let string = 0; string < profile.tuning.length; string += 1) {
-    const open = profile.tuning[string];
+  for (let string = 0; string < stringed.tuning.length; string += 1) {
+    const open = stringed.tuning[string];
     if (open === void 0) {
       continue;
     }
     const fret = pitch - open;
-    if (fret >= 0 && fret <= profile.frets) {
+    if (fret >= 0 && fret <= stringed.frets) {
       out.push({ string, fret });
     }
   }
   return out;
 }
 function foldIntoRange(pitch, profile) {
-  if (canSound(profile, pitch)) {
+  const resolved = toInstrumentProfile(profile, "instrument");
+  assertMidiPitch(pitch, "pitch");
+  return foldIn(pitch, resolved);
+}
+function foldIn(pitch, resolved) {
+  if (soundsIn(resolved, pitch)) {
     return pitch;
   }
-  const { low, high } = instrumentRange(profile);
-  for (let candidate = pitch + 12; candidate <= high; candidate += 12) {
-    if (canSound(profile, candidate)) {
-      return candidate;
+  const { low, high } = rangeIn(resolved);
+  const first = pitch + 12 * Math.ceil((low - pitch) / 12);
+  let best;
+  for (let candidate = first; candidate <= high; candidate += 12) {
+    if (!soundsIn(resolved, candidate)) {
+      continue;
     }
-  }
-  for (let candidate = pitch - 12; candidate >= low; candidate -= 12) {
-    if (canSound(profile, candidate)) {
-      return candidate;
+    if (best === void 0 || Math.abs(candidate - pitch) <= Math.abs(best - pitch)) {
+      best = candidate;
     }
   }
-  return pitch;
+  return best ?? pitch;
 }
 
 // src/core/instrument/playability.ts
@@ -138,13 +179,13 @@ var DIFFICULTY_SCALE = 12;
 var MIN_DIFFICULTY = 1;
 var MAX_DIFFICULTY = 5;
 var STRING_CROSSING_COST = 2;
-var ONSET_GRID = 128;
-var EPS = 1e-9;
+var SIMULTANEITY_BEATS = 1 / 128;
 function playability(notes, profile, bpm) {
   assertNoteEvents(notes, "playability notes", { allowNonPositiveDuration: true });
   if (bpm !== void 0) {
     assertRange(bpm, Number.MIN_VALUE, 1e3, "playability bpm");
   }
+  const instrument = toInstrumentProfile(profile, "playability profile");
   const order = notes.map((_, index) => index).sort((a, b) => {
     const left = notes[a];
     const right = notes[b];
@@ -161,11 +202,13 @@ function playability(notes, profile, bpm) {
     movement: 0,
     secondsPerBeat: bpm === void 0 ? void 0 : 60 / bpm
   };
-  checkExistence(state, profile);
-  if (profile.kind === "stringed") {
-    placeOnNeck(state, profile);
+  if (instrument.kind === "stringed") {
+    checkExistence(state, instrument, (pitch) => soundsIn(instrument, pitch));
+    placeOnNeck(state, instrument);
   } else {
-    placeOnKit(state, profile);
+    const kit = readKit(instrument);
+    checkExistence(state, instrument, (pitch) => limbsFor(kit, pitch).length > 0);
+    placeOnKit(state, kit);
   }
   return {
     difficulty: difficultyOf(state, bpm),
@@ -173,13 +216,13 @@ function playability(notes, profile, bpm) {
     placements: state.placements
   };
 }
-function checkExistence(state, profile) {
+function checkExistence(state, profile, sounds) {
   for (const index of state.order) {
     const note = state.notes[index];
     if (!note) {
       continue;
     }
-    if (!canSound(profile, note.pitch)) {
+    if (!sounds(note.pitch)) {
       state.issues.push({
         type: "noteOutOfRange",
         layer: 1,
@@ -202,33 +245,35 @@ function checkExistence(state, profile) {
     }
   }
 }
+function isSimultaneous(anchorBeat, startBeat) {
+  return startBeat - anchorBeat <= SIMULTANEITY_BEATS + BEAT_EPS;
+}
 function soundingGroups(state) {
   const groups = [];
   let active = [];
   let cursor = 0;
-  let previousKey = Number.NaN;
+  let anchor;
   for (const index of state.order) {
     const note = state.notes[index];
     if (!note) {
       continue;
     }
-    const key = Math.round(note.startBeat * ONSET_GRID);
-    if (key === previousKey) {
+    if (anchor !== void 0 && isSimultaneous(anchor, note.startBeat)) {
       continue;
     }
-    previousKey = key;
     const at = note.startBeat;
+    anchor = at;
     active = active.filter((member) => {
       const held = state.notes[member];
-      return held !== void 0 && held.startBeat + held.durationBeat > at + EPS;
+      return held !== void 0 && held.startBeat + held.durationBeat > at + BEAT_EPS;
     });
     while (cursor < state.order.length) {
       const candidateIndex = state.order[cursor];
       const candidate = candidateIndex === void 0 ? void 0 : state.notes[candidateIndex];
-      if (!candidate || candidate.startBeat > at + EPS) {
+      if (!candidate || !isSimultaneous(at, candidate.startBeat)) {
         break;
       }
-      if (candidateIndex !== void 0 && candidate.startBeat + candidate.durationBeat > at + EPS) {
+      if (candidateIndex !== void 0 && candidate.startBeat + candidate.durationBeat > at + BEAT_EPS) {
         active.push(candidateIndex);
       }
       cursor += 1;
@@ -248,12 +293,12 @@ function placeOnNeck(state, profile) {
     if (!note || !placement) {
       continue;
     }
-    const candidates = fingeringsFor(profile, note.pitch);
+    const candidates = fingeringsIn(profile, note.pitch);
     if (candidates.length === 0) {
       continue;
     }
     const free = candidates.filter(
-      (candidate) => (stringFreeAt[candidate.string] ?? 0) <= note.startBeat + EPS
+      (candidate) => (stringFreeAt[candidate.string] ?? 0) <= note.startBeat + BEAT_EPS
     );
     if (free.length === 0) {
       const blocked = candidates.map((candidate) => stringHeldBy[candidate.string]).filter((held) => held !== void 0);
@@ -304,7 +349,7 @@ function checkShiftSpeed(state, profile, fromIndex, toIndex, from, to) {
   }
   const seconds = (note.startBeat - previousNote.startBeat) * secondsPerBeat;
   const shift = Math.abs(to.fret - from.fret);
-  if (seconds <= EPS || shift === 0) {
+  if (seconds <= BEAT_EPS || shift === 0) {
     return;
   }
   if (shift / seconds > MAX_FRET_SHIFT_PER_SECOND) {
@@ -350,61 +395,103 @@ function checkPolyphony(state, profile, group) {
     message: `${group.members.length} notes sound at once; ${profile.name} has ${profile.polyphony}`
   });
 }
-function placeOnKit(state, profile) {
-  const limbForVoice = /* @__PURE__ */ new Map();
-  const lastStroke = /* @__PURE__ */ new Map();
+var NO_LIMBS = Object.freeze([]);
+function readKit(profile) {
+  const limbs = /* @__PURE__ */ new Map();
+  for (const key of Object.keys(profile.reach)) {
+    const pitch = Number(key);
+    limbs.set(pitch, reachOf(profile, pitch));
+  }
+  return { profile, limbs, overdub: new Set(profile.overdub ?? []) };
+}
+function limbsFor(kit, pitch) {
+  if (pitch === void 0) {
+    return NO_LIMBS;
+  }
+  return kit.limbs.get(pitch) ?? NO_LIMBS;
+}
+function passesAt(state, kit, members) {
+  const played = { id: "kit", members: [] };
+  const overdubs = /* @__PURE__ */ new Map();
+  for (const index of members) {
+    const pitch = state.notes[index]?.pitch;
+    if (pitch === void 0 || !kit.overdub.has(pitch)) {
+      played.members.push(index);
+      continue;
+    }
+    let pass = overdubs.get(pitch);
+    if (!pass) {
+      pass = { id: `overdub ${pitch}`, members: [] };
+      overdubs.set(pitch, pass);
+    }
+    pass.members.push(index);
+  }
+  return [played, ...overdubs.values()];
+}
+function placePass(state, kit, pass, memory) {
+  const taken = /* @__PURE__ */ new Set();
+  let conflicted = false;
+  const members = [...pass.members].sort((a, b) => {
+    const left = limbsFor(kit, state.notes[a]?.pitch);
+    const right = limbsFor(kit, state.notes[b]?.pitch);
+    return left.length - right.length || a - b;
+  });
+  for (const index of members) {
+    const note = state.notes[index];
+    const placement = state.placements[index];
+    if (!note || !placement) {
+      continue;
+    }
+    const candidates = limbsFor(kit, note.pitch);
+    if (candidates.length === 0) {
+      continue;
+    }
+    const preferred = memory.limbForVoice.get(note.pitch);
+    const free = candidates.filter((limb) => !taken.has(limb));
+    const chosen = free.length === 0 ? candidates[0] : preferred !== void 0 && free.includes(preferred) ? preferred : free[0];
+    if (free.length === 0) {
+      conflicted = true;
+    }
+    if (chosen === void 0) {
+      continue;
+    }
+    taken.add(chosen);
+    placement.limb = chosen;
+    memory.limbForVoice.set(note.pitch, chosen);
+    state.movement += 1;
+    const strokeKey = `${pass.id} ${chosen}`;
+    const previousIndex = memory.lastStroke.get(strokeKey);
+    if (previousIndex !== void 0) {
+      const previousNote = state.notes[previousIndex];
+      if (previousNote && previousNote.pitch !== note.pitch) {
+        state.movement += 1;
+      }
+      checkStrokeSpeed(state, kit.profile, previousIndex, index, chosen);
+    }
+    memory.lastStroke.set(strokeKey, index);
+  }
+  return conflicted;
+}
+function placeOnKit(state, kit) {
+  const memory = { limbForVoice: /* @__PURE__ */ new Map(), lastStroke: /* @__PURE__ */ new Map() };
   for (const group of onsetGroups(state)) {
-    const taken = /* @__PURE__ */ new Set();
     let conflicted = false;
-    const members = [...group.members].sort((a, b) => {
-      const left = reachOf(profile, state.notes[a]?.pitch);
-      const right = reachOf(profile, state.notes[b]?.pitch);
-      return left.length - right.length || a - b;
-    });
-    for (const index of members) {
-      const note = state.notes[index];
-      const placement = state.placements[index];
-      if (!note || !placement) {
-        continue;
-      }
-      const candidates = reachOf(profile, note.pitch);
-      if (candidates.length === 0) {
+    for (const pass of passesAt(state, kit, group.members)) {
+      if (!placePass(state, kit, pass, memory)) {
         continue;
       }
-      const preferred = limbForVoice.get(note.pitch);
-      const free = candidates.filter((limb) => !taken.has(limb));
-      const chosen = free.length === 0 ? candidates[0] : preferred !== void 0 && free.includes(preferred) ? preferred : free[0];
-      if (free.length === 0) {
-        conflicted = true;
-      }
-      if (chosen === void 0) {
-        continue;
-      }
-      taken.add(chosen);
-      placement.limb = chosen;
-      limbForVoice.set(note.pitch, chosen);
-      state.movement += 1;
-      const previousIndex = lastStroke.get(chosen);
-      if (previousIndex !== void 0) {
-        const previousNote = state.notes[previousIndex];
-        if (previousNote && previousNote.pitch !== note.pitch) {
-          state.movement += 1;
-        }
-        checkStrokeSpeed(state, profile, previousIndex, index, chosen);
-      }
-      lastStroke.set(chosen, index);
-    }
-    if (conflicted) {
+      conflicted = true;
       state.issues.push({
         type: "limbConflict",
         layer: 2,
-        notes: [...group.members].sort((a, b) => a - b),
+        notes: [...pass.members].sort((a, b) => a - b),
         startBeat: group.startBeat,
         impossible: true,
-        message: `${group.members.length} simultaneous strokes cannot be shared among the limbs of ${profile.name}`
+        message: `${pass.members.length} simultaneous strokes cannot be shared among the limbs of ${kit.profile.name}`
       });
-    } else {
-      checkPolyphony(state, profile, group);
+    }
+    if (!conflicted) {
+      checkPolyphony(state, kit.profile, group);
     }
   }
 }
@@ -419,7 +506,7 @@ function checkStrokeSpeed(state, profile, fromIndex, toIndex, limb) {
     return;
   }
   const seconds = (note.startBeat - previousNote.startBeat) * secondsPerBeat;
-  if (seconds <= EPS || seconds >= MIN_LIMB_STROKE_SECONDS) {
+  if (seconds <= BEAT_EPS || seconds >= MIN_LIMB_STROKE_SECONDS) {
     return;
   }
   state.issues.push({
@@ -433,18 +520,15 @@ function checkStrokeSpeed(state, profile, fromIndex, toIndex, limb) {
 }
 function onsetGroups(state) {
   const groups = [];
-  let key = Number.NaN;
   let current;
   for (const index of state.order) {
     const note = state.notes[index];
-    if (!note) {
+    if (!note || note.durationBeat <= 0) {
       continue;
     }
-    const onsetKey = Math.round(note.startBeat * ONSET_GRID);
-    if (!current || onsetKey !== key) {
+    if (!current || !isSimultaneous(current.startBeat, note.startBeat)) {
       current = { startBeat: note.startBeat, members: [] };
       groups.push(current);
-      key = onsetKey;
     }
     current.members.push(index);
   }
@@ -461,7 +545,7 @@ function difficultyOf(state, bpm) {
     last = Math.max(last, note.startBeat + Math.max(0, note.durationBeat));
   }
   const spanBeats = last - first;
-  if (!Number.isFinite(spanBeats) || spanBeats <= EPS) {
+  if (!Number.isFinite(spanBeats) || spanBeats <= BEAT_EPS) {
     return MIN_DIFFICULTY;
   }
   const seconds = spanBeats * 60 / (bpm ?? REFERENCE_BPM);
@@ -666,14 +750,17 @@ function createRng(seed) {
 }
 
 export {
-  ARTICULATIONS,
   LIMBS,
   toInstrumentProfile,
   toStringedProfile,
   instrumentRange,
+  rangeIn,
   canSound,
+  soundsIn,
   fingeringsFor,
+  fingeringsIn,
   foldIntoRange,
+  foldIn,
   playability,
   BASS_4_STRING,
   BASS_5_STRING,
@@ -687,4 +774,4 @@ export {
   resolveAlgorithmVersion,
   createRng
 };
-//# sourceMappingURL=chunk-FVSI36UV.js.map
+//# sourceMappingURL=chunk-7KG3RTYS.js.map