@libraz/libcantus 0.9.4 → 1.0.0

package/dist/theory/index.js

@@ -1,42 +1,37 @@
-import "../chunk-N6IHQUOX.js";
-import {
-  roleOf
-} from "../chunk-NKIBQ6PT.js";
-import {
-  NoteSafety,
-  ReasonFlag,
-  enumerateSafePitches,
-  evaluateSafety
-} from "../chunk-NYYWMV2C.js";
+import "../chunk-HFPS7JFD.js";
 import {
   SATB_RANGES,
+  TRANSPOSING_INSTRUMENTS,
   availableTensions,
   avoidNotes,
+  checkPartWriting,
+  checkSpecies,
   chordScaleReport,
   chordScales,
-  formatChordSymbol,
+  figuredBassOf,
+  figuredBassRealization,
+  instrumentTransposition,
   nextVoicing,
-  noteNames,
-  parseChordSymbol,
+  realizeFiguredBass,
   scaleMatchesChord,
   scalesForChanges,
-  spellChord,
-  spellChordFromRoot,
-  spellPitch,
-  spellPitchClass,
-  spellPitchClasses,
-  spellScale,
-  transposeChordSymbol,
+  spellVoicing,
+  toSoundingPitch,
+  toWrittenPitch,
   voiceChord,
   voiceChordStyled,
   voiceLeadingCost,
   voiceProgression
-} from "../chunk-RK35RIN7.js";
+} from "../chunk-H3VORETI.js";
+import {
+  roleOf
+} from "../chunk-KNJEKLKV.js";
 import {
   ALTERED_MASK,
   BLUES_MASK,
   CHROMATIC_MASK,
   DORIAN_MASK,
+  DOUBLE_HARMONIC_MASK,
   HARMONIC_MINOR_MASK,
   LOCRIAN_MASK,
   LOCRIAN_NATURAL2_MASK,
@@ -44,21 +39,40 @@ import {
   LYDIAN_MASK,
   MAJOR_MASK,
   MAJOR_PENTATONIC_MASK,
+  MARWA_MASK,
   MELODIC_MINOR_MASK,
   MINOR_PENTATONIC_MASK,
   MIXOLYDIAN_B13_MASK,
   MIXOLYDIAN_MASK,
+  MIYAKO_BUSHI_MASK,
   NAMED_SCALES,
   NATURAL_MINOR_MASK,
+  NoteSafety,
   OCTATONIC_HALF_WHOLE_MASK,
   OCTATONIC_WHOLE_HALF_MASK,
   PHRYGIAN_DOMINANT_MASK,
   PHRYGIAN_MASK,
+  PROFILE_WEIGHTS,
+  PURVI_MASK,
+  RITSU_MASK,
+  RYUKYU_MASK,
+  ReasonFlag,
+  SCALE_ALIASES,
+  SCALE_SYSTEMS,
+  TODI_MASK,
   WHOLE_TONE_MASK,
+  WORLD_SCALES,
   chordFromDegree,
+  chordFromSpan,
+  chordFromSpec,
   chordPitchClasses,
   chordQualities,
+  chordSpecIntervals,
+  chordSpecOf,
+  chordSpecQuality,
   chordToneRole,
+  classifySpelledInterval,
+  createsBattuta,
   createsHiddenParallelPerfect,
   createsParallelOctave,
   createsParallelPerfect,
@@ -69,30 +83,63 @@ import {
   diatonicPitchClasses,
   diatonicSeventh,
   diatonicTriad,
+  dominantKeyOf,
+  enharmonicKeyOf,
+  enumerateSafePitches,
+  evaluateSafety,
   exceedsSpacing,
+  formatChordSymbol,
   intervalAboveRoot,
+  isAugmentedMelodicInterval,
   isChordMember,
   isForbiddenMelodicLeap,
   isLeadingToneResolution,
   isScaleTone,
+  keyFromFifths,
+  keyRelationBetween,
+  keySignatureFifths,
   majorKey,
   makeChord,
   maskFromOffsets,
   minorKey,
   namedScaleMask,
   nearestScaleTone,
+  noteNames,
+  parallelKeyOf,
+  parseChordSymbol,
   pitchToScaleDegree,
+  profileWeights,
+  relatedKeysOf,
+  relativeKeyOf,
   requireScaleMask,
+  resolveScaleName,
   scaleByName,
+  scaleSystemOf,
   scaleTonesInDegreeOrder,
-  transposeChord
-} from "../chunk-D2FAJBYL.js";
-import "../chunk-XEBG3G53.js";
+  spanFromChord,
+  spellChord,
+  spellChordFromRoot,
+  spellPitch,
+  spellPitchClass,
+  spellPitchClasses,
+  spellScale,
+  spelledKeyOf,
+  subdominantKeyOf,
+  supportsFunctionalHarmony,
+  toChordData,
+  toKeyScale,
+  transposeChord,
+  transposeChordSymbol,
+  tryParseChordSymbol,
+  voiceIndependence
+} from "../chunk-INHVXP6Z.js";
+import "../chunk-VTI6FOLB.js";
 export {
   ALTERED_MASK,
   BLUES_MASK,
   CHROMATIC_MASK,
   DORIAN_MASK,
+  DOUBLE_HARMONIC_MASK,
   HARMONIC_MINOR_MASK,
   LOCRIAN_MASK,
   LOCRIAN_NATURAL2_MASK,
@@ -100,10 +147,12 @@ export {
   LYDIAN_MASK,
   MAJOR_MASK,
   MAJOR_PENTATONIC_MASK,
+  MARWA_MASK,
   MELODIC_MINOR_MASK,
   MINOR_PENTATONIC_MASK,
   MIXOLYDIAN_B13_MASK,
   MIXOLYDIAN_MASK,
+  MIYAKO_BUSHI_MASK,
   NAMED_SCALES,
   NATURAL_MINOR_MASK,
   NoteSafety,
@@ -111,17 +160,35 @@ export {
   OCTATONIC_WHOLE_HALF_MASK,
   PHRYGIAN_DOMINANT_MASK,
   PHRYGIAN_MASK,
+  PROFILE_WEIGHTS,
+  PURVI_MASK,
+  RITSU_MASK,
+  RYUKYU_MASK,
   ReasonFlag,
   SATB_RANGES,
+  SCALE_ALIASES,
+  SCALE_SYSTEMS,
+  TODI_MASK,
+  TRANSPOSING_INSTRUMENTS,
   WHOLE_TONE_MASK,
+  WORLD_SCALES,
   availableTensions,
   avoidNotes,
+  checkPartWriting,
+  checkSpecies,
   chordFromDegree,
+  chordFromSpan,
+  chordFromSpec,
   chordPitchClasses,
   chordQualities,
   chordScaleReport,
   chordScales,
+  chordSpecIntervals,
+  chordSpecOf,
+  chordSpecQuality,
   chordToneRole,
+  classifySpelledInterval,
+  createsBattuta,
   createsHiddenParallelPerfect,
   createsParallelOctave,
   createsParallelPerfect,
@@ -132,15 +199,24 @@ export {
   diatonicPitchClasses,
   diatonicSeventh,
   diatonicTriad,
+  dominantKeyOf,
+  enharmonicKeyOf,
   enumerateSafePitches,
   evaluateSafety,
   exceedsSpacing,
+  figuredBassOf,
+  figuredBassRealization,
   formatChordSymbol,
+  instrumentTransposition,
   intervalAboveRoot,
+  isAugmentedMelodicInterval,
   isChordMember,
   isForbiddenMelodicLeap,
   isLeadingToneResolution,
   isScaleTone,
+  keyFromFifths,
+  keyRelationBetween,
+  keySignatureFifths,
   majorKey,
   makeChord,
   maskFromOffsets,
@@ -149,24 +225,42 @@ export {
   nearestScaleTone,
   nextVoicing,
   noteNames,
+  parallelKeyOf,
   parseChordSymbol,
   pitchToScaleDegree,
+  profileWeights,
+  realizeFiguredBass,
+  relatedKeysOf,
+  relativeKeyOf,
   requireScaleMask,
+  resolveScaleName,
   roleOf,
   scaleByName,
   scaleMatchesChord,
+  scaleSystemOf,
   scaleTonesInDegreeOrder,
   scalesForChanges,
+  spanFromChord,
   spellChord,
   spellChordFromRoot,
   spellPitch,
   spellPitchClass,
   spellPitchClasses,
   spellScale,
+  spellVoicing,
+  spelledKeyOf,
+  subdominantKeyOf,
+  supportsFunctionalHarmony,
+  toChordData,
+  toKeyScale,
+  toSoundingPitch,
+  toWrittenPitch,
   transposeChord,
   transposeChordSymbol,
+  tryParseChordSymbol,
   voiceChord,
   voiceChordStyled,
+  voiceIndependence,
   voiceLeadingCost,
   voiceProgression
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@libraz/libcantus",
-  "version": "0.9.4",
-  "description": "Pure-TypeScript music-theory and composition primitives (intervals, scales, chords).",
+  "version": "1.0.0",
+  "description": "Pure-TypeScript music theory engine: harmonic analysis, chord and scale vocabulary, voicing, reharmonization, and seeded part generation over MIDI note events.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "libraz",
@@ -20,16 +20,18 @@
     "scales",
     "intervals",
     "harmony",
-    "composition"
+    "composition",
+    "midi",
+    "chord-detection",
+    "voicing",
+    "reharmonization",
+    "arrangement",
+    "generative-music"
   ],
   "engines": {
-    "node": ">=22 <23"
-  },
-  "packageManager": "yarn@4.17.0",
-  "volta": {
-    "node": "22.22.3",
-    "yarn": "4.17.0"
+    "node": ">=22"
   },
+  "packageManager": "yarn@4.18.0",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -118,6 +120,7 @@
   "files": [
     "dist",
     "README.md",
+    "README_ja.md",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -127,7 +130,8 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
-    "typecheck": "tsc --noEmit",
+    "examples": "vitest list >/dev/null",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json && yarn examples && tsc -p tsconfig.examples.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -137,8 +141,9 @@
     "prepublishOnly": "yarn build"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.5",
+    "@biomejs/biome": "2.5.8",
     "@libraz/typedoc-theme": "^0.1.1",
+    "@types/node": "^26.2.0",
     "@vitest/coverage-v8": "4.1.10",
     "tsup": "8.5.1",
     "typedoc": "0.28.20",

package/dist/chunk-36N73KZ3.cjs

@@ -1,246 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
-
-
-
-
-
-
-
-
-
-
-
-
-var _chunk7MGZ7D62cjs = require('./chunk-7MGZ7D62.cjs');
-
-// src/core/meter/index.ts
-var EPS = 1e-9;
-function isMultiple(value, unit) {
-  if (unit === 0) {
-    return false;
-  }
-  const ratio = value / unit;
-  return Math.abs(ratio - Math.round(ratio)) < EPS;
-}
-function parseTimeSignature(text) {
-  const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(text);
-  if (!match) {
-    throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(`Invalid time signature: ${text}`);
-  }
-  const numerator = Number.parseInt(_nullishCoalesce(match[1], () => ( "")), 10);
-  const denominator = Number.parseInt(_nullishCoalesce(match[2], () => ( "")), 10);
-  if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator) || numerator <= 0 || denominator <= 0) {
-    throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(`Invalid time signature: ${text}`);
-  }
-  return _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, { numerator, denominator }, `time signature ${text}`);
-}
-function formatTimeSignature(ts, opts = {}) {
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  if (opts.grouping === true && ts.grouping !== void 0) {
-    return `${ts.grouping.join("+")}/${ts.denominator}`;
-  }
-  return `${ts.numerator}/${ts.denominator}`;
-}
-function isCompound(ts) {
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  return _chunk7MGZ7D62cjs.isCompoundNumerator.call(void 0, ts.numerator) && !_chunk7MGZ7D62cjs.isAdditiveReading.call(void 0, ts);
-}
-function beatsPerBar(ts) {
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  return _chunk7MGZ7D62cjs.barBeatsOf.call(void 0, ts);
-}
-function pulsesPerBar(ts) {
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  return _chunk7MGZ7D62cjs.pulseCountOf.call(void 0, ts);
-}
-function isGroupHead(grouping, pulseIndex) {
-  let acc = 0;
-  for (const g of grouping) {
-    if (acc === pulseIndex) {
-      return true;
-    }
-    acc += g;
-  }
-  return false;
-}
-function beatToBarPosition(beatInQuarters, ts) {
-  _chunk7MGZ7D62cjs.assertFiniteNumber.call(void 0, beatInQuarters, "beat");
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  const barLen = _chunk7MGZ7D62cjs.barBeatsOf.call(void 0, ts);
-  const bar = Math.floor(beatInQuarters / barLen);
-  return { bar, beat: beatInQuarters - bar * barLen };
-}
-function pulseBeats(ts) {
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  return _chunk7MGZ7D62cjs.pulseBeatsOf.call(void 0, ts);
-}
-function barPositionToPulse(pos, ts) {
-  _chunk7MGZ7D62cjs.assertFiniteNumber.call(void 0, pos.beat, "position.beat");
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  return pos.beat / _chunk7MGZ7D62cjs.pulseBeatsOf.call(void 0, ts) + 1;
-}
-function formatBarPosition(beatInQuarters, ts, decimals = 2) {
-  const position = beatToBarPosition(beatInQuarters, ts);
-  const pulse = barPositionToPulse(position, ts);
-  const rounded = Number(pulse.toFixed(decimals));
-  return `${position.bar + 1}.${rounded}`;
-}
-function barPositionToBeat(pos, ts) {
-  _chunk7MGZ7D62cjs.assertInteger.call(void 0, pos.bar, "bar position bar");
-  _chunk7MGZ7D62cjs.assertFiniteNumber.call(void 0, pos.beat, "bar position beat");
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  return pos.bar * _chunk7MGZ7D62cjs.barBeatsOf.call(void 0, ts) + pos.beat;
-}
-function metricWeight(beatInQuarters, ts) {
-  _chunk7MGZ7D62cjs.assertFiniteNumber.call(void 0, beatInQuarters, "beat");
-  _chunk7MGZ7D62cjs.assertTimeSignature.call(void 0, ts);
-  const barLen = _chunk7MGZ7D62cjs.barBeatsOf.call(void 0, ts);
-  const beat = beatInQuarters - Math.floor(beatInQuarters / barLen) * barLen;
-  const pulse = _chunk7MGZ7D62cjs.pulseBeatsOf.call(void 0, ts);
-  if (!isMultiple(beat, pulse)) {
-    return 0;
-  }
-  const pulses = _chunk7MGZ7D62cjs.pulseCountOf.call(void 0, ts);
-  const pulseIndex = Math.round(beat / pulse) % pulses;
-  if (pulseIndex === 0) {
-    return 3;
-  }
-  const grouping = ts.grouping;
-  if (grouping !== void 0) {
-    return isGroupHead(grouping, pulseIndex) ? 2 : 1;
-  }
-  if (pulses % 2 === 0 && pulseIndex === pulses / 2) {
-    return 2;
-  }
-  return 1;
-}
-function isStrongBeat(beatInQuarters, ts) {
-  return metricWeight(beatInQuarters, ts) >= 2;
-}
-function tuplet(totalBeats, count) {
-  _chunk7MGZ7D62cjs.assertRange.call(void 0, totalBeats, 0, Number.MAX_SAFE_INTEGER, "tuplet total beats");
-  _chunk7MGZ7D62cjs.assertPositiveInt.call(void 0, count, "tuplet count");
-  return new Array(count).fill(totalBeats / count);
-}
-
-// src/core/event-index/index.ts
-var EPS2 = 1e-9;
-function upperBound(values, beat) {
-  let low = 0;
-  let high = values.length;
-  while (low < high) {
-    const middle = Math.floor((low + high) / 2);
-    if ((_nullishCoalesce(_optionalChain([values, 'access', _ => _[middle], 'optionalAccess', _2 => _2.note, 'access', _3 => _3.startBeat]), () => ( Number.POSITIVE_INFINITY))) <= beat) {
-      low = middle + 1;
-    } else {
-      high = middle;
-    }
-  }
-  return low;
-}
-function createNoteEventIndex(events, options = {}) {
-  _chunk7MGZ7D62cjs.assertNoteEvents.call(void 0, events, _nullishCoalesce(options.name, () => ( "note events")), options);
-  const tieBreak = _nullishCoalesce(options.tieBreak, () => ( "highest"));
-  const notes = events.map((note, originalIndex) => ({
-    note,
-    originalIndex,
-    endBeat: note.startBeat + note.durationBeat
-  })).sort((a, b) => a.note.startBeat - b.note.startBeat || a.originalIndex - b.originalIndex);
-  let prefixMaxEnd;
-  const maxEndUpTo = (index) => {
-    if (prefixMaxEnd === void 0) {
-      const prefix = [];
-      let maxEnd = Number.NEGATIVE_INFINITY;
-      for (const indexed of notes) {
-        maxEnd = Math.max(maxEnd, indexed.endBeat);
-        prefix.push(maxEnd);
-      }
-      prefixMaxEnd = prefix;
-    }
-    return _nullishCoalesce(prefixMaxEnd[index], () => ( Number.NEGATIVE_INFINITY));
-  };
-  return {
-    notes,
-    at(beat) {
-      let index = upperBound(notes, beat + EPS2) - 1;
-      let best;
-      while (index >= 0) {
-        if (maxEndUpTo(index) <= beat + EPS2) {
-          break;
-        }
-        const indexed = notes[index];
-        index -= 1;
-        if (indexed === void 0 || indexed.note.durationBeat <= 0 || indexed.note.startBeat - EPS2 > beat || beat >= indexed.endBeat - EPS2) {
-          continue;
-        }
-        if (best === void 0) {
-          best = indexed;
-          if (tieBreak === "last") {
-            break;
-          }
-          continue;
-        }
-        if (Math.abs(indexed.note.startBeat - best.note.startBeat) >= EPS2) {
-          break;
-        }
-        const higher = indexed.note.pitch > best.note.pitch;
-        if (tieBreak === "highest" ? higher : !higher) {
-          best = indexed;
-        }
-      }
-      return best;
-    },
-    attacksAt(beat) {
-      let index = upperBound(notes, beat + EPS2) - 1;
-      while (index >= 0) {
-        const candidate = notes[index];
-        if (candidate === void 0 || Math.abs(candidate.note.startBeat - beat) >= EPS2) {
-          return false;
-        }
-        if (candidate.note.durationBeat > 0) {
-          return true;
-        }
-        index -= 1;
-      }
-      return false;
-    },
-    onsetsBetween(startBeat, endBeat) {
-      const result = [];
-      let index = upperBound(notes, startBeat + EPS2);
-      while (index < notes.length) {
-        const indexed = notes[index];
-        const onset = _optionalChain([indexed, 'optionalAccess', _4 => _4.note, 'access', _5 => _5.startBeat]);
-        if (indexed === void 0 || onset === void 0 || onset >= endBeat - EPS2) {
-          break;
-        }
-        index += 1;
-        if (indexed.note.durationBeat <= 0) {
-          continue;
-        }
-        const previous = result[result.length - 1];
-        if (previous === void 0 || Math.abs(previous - onset) >= EPS2) {
-          result.push(onset);
-        }
-      }
-      return result;
-    }
-  };
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-exports.parseTimeSignature = parseTimeSignature; exports.formatTimeSignature = formatTimeSignature; exports.isCompound = isCompound; exports.beatsPerBar = beatsPerBar; exports.pulsesPerBar = pulsesPerBar; exports.beatToBarPosition = beatToBarPosition; exports.pulseBeats = pulseBeats; exports.barPositionToPulse = barPositionToPulse; exports.formatBarPosition = formatBarPosition; exports.barPositionToBeat = barPositionToBeat; exports.metricWeight = metricWeight; exports.isStrongBeat = isStrongBeat; exports.tuplet = tuplet; exports.createNoteEventIndex = createNoteEventIndex;
-//# sourceMappingURL=chunk-36N73KZ3.cjs.map

package/dist/chunk-36N73KZ3.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/libcantus/libcantus/dist/chunk-36N73KZ3.cjs","../src/core/meter/index.ts","../src/core/event-index/index.ts"],"names":[],"mappings":"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","file":"/home/runner/work/libcantus/libcantus/dist/chunk-36N73KZ3.cjs","sourcesContent":[null,"/**\n * Meter and time signatures: bar/beat arithmetic, simple vs. compound meters,\n * metric-accent hierarchy, and tuplet subdivision.\n *\n * Positions and durations are measured in quarter-note beats, matching the rest\n * of the library's beat convention (four quarter-note beats per bar in 4/4).\n */\n\nimport { InvalidInputError } from '../errors/index.js';\nimport {\n  assertFiniteNumber,\n  assertInteger,\n  assertPositiveInt,\n  assertRange,\n  assertTimeSignature,\n} from '../validation/index.js';\nimport {\n  barBeatsOf,\n  isAdditiveReading,\n  isCompoundNumerator,\n  pulseBeatsOf,\n  pulseCountOf,\n} from './internal.js';\n\n/**\n * A time signature as a numerator over a note-value denominator.\n *\n * @category Rhythm & Meter\n */\nexport type TimeSignature = {\n  numerator: number;\n  denominator: number;\n  /**\n   * Optional additive grouping of the bar's main pulses, as the felt-beat\n   * lengths in pulses — e.g. `[2, 2, 3]` for a 2+2+3 reading of 7/8, or\n   * `[3, 2]` for 5/8. The entries must be positive integers summing to the\n   * numerator.\n   *\n   * A compound numerator accepts both readings. 9/8 groups its three dotted\n   * pulses as `[1, 1, 1]`, or reads additively as `[2, 2, 2, 3]` quavers; a\n   * grouping that sums to the numerator selects the additive reading, so\n   * aksak and other additive metres are expressible. {@link pulsesPerBar}\n   * and {@link isCompound} follow whichever reading the grouping selects.\n   *\n   * When present, the head pulse of each group (other than the downbeat) is\n   * treated as a secondary strong pulse by\n   * {@link metricWeight}/{@link isStrongBeat}; when absent, all main pulses\n   * are weighted equally as flat, evenly divided pulses.\n   */\n  grouping?: number[];\n};\n\n/**\n * A position expressed as a bar index and a quarter-note offset within the bar.\n *\n * @category Rhythm & Meter\n */\nexport type BarPosition = {\n  /** 0-based bar index. {@link formatBarPosition} renders it 1-based. */\n  bar: number;\n  /**\n   * Quarter-note offset from the start of the bar — not the felt beat. In 6/8\n   * the second felt beat is at `beat: 1.5`; {@link barPositionToPulse} converts\n   * to felt-beat numbering.\n   */\n  beat: number;\n};\n\nconst EPS = 1e-9;\n\n/** Whether `value` is an integer multiple of `unit` (within a float tolerance). */\nfunction isMultiple(value: number, unit: number): boolean {\n  if (unit === 0) {\n    return false;\n  }\n  const ratio = value / unit;\n  return Math.abs(ratio - Math.round(ratio)) < EPS;\n}\n\n/**\n * Parse a time signature such as `\"4/4\"` or `\"6/8\"`.\n *\n * @param text The signature text.\n * @returns The parsed time signature.\n * @throws If the text is not `n/d` with positive integers.\n * @example\n * ```ts\n * import { parseTimeSignature } from '@libraz/libcantus';\n * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }\n * ```\n * @category Rhythm & Meter\n */\nexport function parseTimeSignature(text: string): TimeSignature {\n  const match = /^\\s*(\\d+)\\s*\\/\\s*(\\d+)\\s*$/.exec(text);\n  if (!match) {\n    throw new InvalidInputError(`Invalid time signature: ${text}`);\n  }\n  const numerator = Number.parseInt(match[1] ?? '', 10);\n  const denominator = Number.parseInt(match[2] ?? '', 10);\n  if (\n    !Number.isSafeInteger(numerator) ||\n    !Number.isSafeInteger(denominator) ||\n    numerator <= 0 ||\n    denominator <= 0\n  ) {\n    throw new InvalidInputError(`Invalid time signature: ${text}`);\n  }\n  // The same signature every consumer validates, validated here too: parsing\n  // a signature the rest of the library rejects only moves the failure.\n  return assertTimeSignature({ numerator, denominator }, `time signature ${text}`);\n}\n\n/**\n * Render a time signature as `\"n/d\"`, or as `\"a+b+c/d\"` when it carries an\n * additive grouping and `grouping` is requested.\n *\n * The plain form drops the grouping, so a round trip through it reads 7/8 as\n * flat rather than as 2+2+3; ask for the additive form to keep it.\n *\n * @param ts The time signature.\n * @param opts Set `grouping: true` to render an additive grouping.\n * @returns The formatted signature.\n * @example\n * ```ts\n * import { formatTimeSignature } from '@libraz/libcantus';\n * const aksak = { numerator: 7, denominator: 8, grouping: [2, 2, 3] };\n * formatTimeSignature(aksak); // '7/8'\n * formatTimeSignature(aksak, { grouping: true }); // '2+2+3/8'\n * ```\n * @category Rhythm & Meter\n */\nexport function formatTimeSignature(ts: TimeSignature, opts: { grouping?: boolean } = {}): string {\n  assertTimeSignature(ts);\n  if (opts.grouping === true && ts.grouping !== undefined) {\n    return `${ts.grouping.join('+')}/${ts.denominator}`;\n  }\n  return `${ts.numerator}/${ts.denominator}`;\n}\n\n/**\n * Whether a meter is compound: its main pulses each divide into three, as in\n * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a\n * multiple of three greater than three, independent of the denominator. Meters\n * like 3/8 and 3/4 (simple triples, numerator 3) are not compound, and neither\n * is a signature whose {@link TimeSignature.grouping} selects the additive\n * reading (9/8 as 2+2+2+3).\n *\n * @param ts The time signature.\n * @returns True for compound meters.\n * @category Rhythm & Meter\n */\nexport function isCompound(ts: TimeSignature): boolean {\n  assertTimeSignature(ts);\n  return isCompoundNumerator(ts.numerator) && !isAdditiveReading(ts);\n}\n\n/**\n * Length of a bar in quarter-note beats.\n *\n * @param ts The time signature.\n * @returns The bar length in quarter notes.\n * @category Rhythm & Meter\n */\nexport function beatsPerBar(ts: TimeSignature): number {\n  assertTimeSignature(ts);\n  return barBeatsOf(ts);\n}\n\n/**\n * Number of main pulses (felt beats) per bar: the numerator for simple meters,\n * a third of it for compound meters.\n *\n * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses\n * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and\n * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set\n * {@link TimeSignature.grouping}; {@link metricWeight} then accents each\n * group's head pulse.\n *\n * @param ts The time signature.\n * @returns The pulse count per bar.\n * @category Rhythm & Meter\n */\nexport function pulsesPerBar(ts: TimeSignature): number {\n  assertTimeSignature(ts);\n  return pulseCountOf(ts);\n}\n\n/** Whether `pulseIndex` is the head pulse of one of the additive groups. */\nfunction isGroupHead(grouping: number[], pulseIndex: number): boolean {\n  let acc = 0;\n  for (const g of grouping) {\n    if (acc === pulseIndex) {\n      return true;\n    }\n    acc += g;\n  }\n  return false;\n}\n\n/**\n * Convert an absolute quarter-note position to a bar index and in-bar offset.\n *\n * @param beatInQuarters Absolute position in quarter-note beats.\n * @param ts The time signature.\n * @returns The bar and in-bar quarter-note offset.\n * @example\n * ```ts\n * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';\n * const ts = parseTimeSignature('4/4');\n * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }\n * ```\n * @category Rhythm & Meter\n */\nexport function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition {\n  assertFiniteNumber(beatInQuarters, 'beat');\n  assertTimeSignature(ts);\n  const barLen = barBeatsOf(ts);\n  const bar = Math.floor(beatInQuarters / barLen);\n  return { bar, beat: beatInQuarters - bar * barLen };\n}\n\n/**\n * Length of one felt beat (main pulse) in quarter-note beats.\n *\n * A quarter note in simple meters, a dotted quarter in compound ones, and one\n * denominator unit in an additive metre. Position displays, click tracks, and\n * score export are all written against this length.\n *\n * @param ts The time signature.\n * @returns The pulse length in quarter-note beats.\n * @example\n * ```ts\n * import { parseTimeSignature, pulseBeats } from '@libraz/libcantus';\n * pulseBeats(parseTimeSignature('6/8')); // 1.5\n * ```\n * @category Rhythm & Meter\n */\nexport function pulseBeats(ts: TimeSignature): number {\n  assertTimeSignature(ts);\n  return pulseBeatsOf(ts);\n}\n\n/**\n * The felt-beat number of a bar position, 1-based.\n *\n * {@link BarPosition.beat} is a quarter-note offset, so in 6/8 the second felt\n * beat reads as 1.5. This is the number a musician says and a position display\n * shows.\n *\n * @param pos The bar position.\n * @param ts The time signature.\n * @returns The 1-based felt-beat number, fractional between pulses.\n * @example\n * ```ts\n * import { barPositionToPulse, parseTimeSignature } from '@libraz/libcantus';\n * barPositionToPulse({ bar: 0, beat: 1.5 }, parseTimeSignature('6/8')); // 2\n * ```\n * @category Rhythm & Meter\n */\nexport function barPositionToPulse(pos: BarPosition, ts: TimeSignature): number {\n  assertFiniteNumber(pos.beat, 'position.beat');\n  assertTimeSignature(ts);\n  return pos.beat / pulseBeatsOf(ts) + 1;\n}\n\n/**\n * Render an absolute position as the `bar.beat` a DAW or a score shows:\n * 1-based bar, 1-based felt beat.\n *\n * @param beatInQuarters Absolute position in quarter-note beats.\n * @param ts The time signature.\n * @param decimals Digits of the fractional beat to keep.\n * @returns The formatted position, e.g. `'3.2'` for bar 3, felt beat 2.\n * @example\n * ```ts\n * import { formatBarPosition, parseTimeSignature } from '@libraz/libcantus';\n * formatBarPosition(7.5, parseTimeSignature('6/8')); // '3.2'\n * ```\n * @category Rhythm & Meter\n */\nexport function formatBarPosition(beatInQuarters: number, ts: TimeSignature, decimals = 2): string {\n  const position = beatToBarPosition(beatInQuarters, ts);\n  const pulse = barPositionToPulse(position, ts);\n  const rounded = Number(pulse.toFixed(decimals));\n  return `${position.bar + 1}.${rounded}`;\n}\n\n/**\n * Convert a bar index and in-bar offset back to an absolute quarter-note\n * position.\n *\n * @param pos The bar position.\n * @param ts The time signature.\n * @returns The absolute position in quarter-note beats.\n * @category Rhythm & Meter\n */\nexport function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number {\n  assertInteger(pos.bar, 'bar position bar');\n  assertFiniteNumber(pos.beat, 'bar position beat');\n  assertTimeSignature(ts);\n  return pos.bar * barBeatsOf(ts) + pos.beat;\n}\n\n/**\n * Metric weight of a position within its bar, on a 0–3 scale:\n * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an\n * off-pulse subdivision.\n *\n * The secondary strong pulse is the bar's midpoint in even simple/compound\n * meters. For an additive/irregular meter with {@link TimeSignature.grouping}\n * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the\n * downbeat is the secondary strong pulse instead; without a grouping every\n * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided\n * pulses).\n *\n * @param beatInQuarters Absolute or in-bar quarter-note position.\n * @param ts The time signature.\n * @returns The metric weight (0–3).\n * @throws If the time signature is malformed, including a grouping that is not\n *   a positive-integer list summing to the pulse count or the numerator.\n * @example\n * ```ts\n * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';\n * const ts = parseTimeSignature('4/4');\n * metricWeight(0, ts); // 3 (the downbeat)\n * ```\n * @category Rhythm & Meter\n */\nexport function metricWeight(beatInQuarters: number, ts: TimeSignature): number {\n  assertFiniteNumber(beatInQuarters, 'beat');\n  assertTimeSignature(ts);\n  const barLen = barBeatsOf(ts);\n  const beat = beatInQuarters - Math.floor(beatInQuarters / barLen) * barLen;\n  const pulse = pulseBeatsOf(ts);\n  if (!isMultiple(beat, pulse)) {\n    return 0;\n  }\n  const pulses = pulseCountOf(ts);\n  const pulseIndex = Math.round(beat / pulse) % pulses;\n  if (pulseIndex === 0) {\n    return 3;\n  }\n  const grouping = ts.grouping;\n  if (grouping !== undefined) {\n    return isGroupHead(grouping, pulseIndex) ? 2 : 1;\n  }\n  if (pulses % 2 === 0 && pulseIndex === pulses / 2) {\n    return 2;\n  }\n  return 1;\n}\n\n/**\n * Whether a position is metrically accented (weight 2 or more — a downbeat or a\n * secondary strong pulse).\n *\n * @param beatInQuarters Absolute or in-bar quarter-note position.\n * @param ts The time signature.\n * @returns True on strong beats.\n * @category Rhythm & Meter\n */\nexport function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean {\n  return metricWeight(beatInQuarters, ts) >= 2;\n}\n\n/**\n * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note\n * triplet is `tuplet(1, 3)`).\n *\n * @param totalBeats Total span in quarter-note beats.\n * @param count Number of equal parts.\n * @returns `count` equal durations summing to `totalBeats`.\n * @throws If `count` is not a positive integer.\n * @category Rhythm & Meter\n */\nexport function tuplet(totalBeats: number, count: number): number[] {\n  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, 'tuplet total beats');\n  assertPositiveInt(count, 'tuplet count');\n  return new Array<number>(count).fill(totalBeats / count);\n}\n","import type { NoteEvent } from '../types.js';\nimport { assertNoteEvents } from '../validation/index.js';\n\n/**\n * A validated note retaining its position in the caller's original array.\n *\n * @category Core\n */\nexport type IndexedNoteEvent = {\n  note: NoteEvent;\n  originalIndex: number;\n  endBeat: number;\n};\n\n/**\n * Which note wins when several sound from the same onset.\n *\n * `'highest'` and `'lowest'` name a voice, so the answer does not depend on the\n * order the caller happened to store the chord in; `'last'` takes the one\n * latest in the input array.\n *\n * @category Core\n */\nexport type OnsetTieBreak = 'highest' | 'lowest' | 'last';\n\n/**\n * Binary-searchable, stable-sorted index over note onsets and active spans.\n *\n * @category Core\n */\nexport type NoteEventIndex = {\n  notes: IndexedNoteEvent[];\n  /**\n   * Latest-onset note sounding at `beat`. Simultaneous onsets are resolved by\n   * the index's {@link OnsetTieBreak}.\n   */\n  at: (beat: number) => IndexedNoteEvent | undefined;\n  /** Whether one or more sounding notes attack at `beat`. */\n  attacksAt: (beat: number) => boolean;\n  /** Unique sounding-note attack beats strictly inside `(startBeat, endBeat)`. */\n  onsetsBetween: (startBeat: number, endBeat: number) => number[];\n};\n\nconst EPS = 1e-9;\n\nfunction upperBound(values: IndexedNoteEvent[], beat: number): number {\n  let low = 0;\n  let high = values.length;\n  while (low < high) {\n    const middle = Math.floor((low + high) / 2);\n    if ((values[middle]?.note.startBeat ?? Number.POSITIVE_INFINITY) <= beat) {\n      low = middle + 1;\n    } else {\n      high = middle;\n    }\n  }\n  return low;\n}\n\n/**\n * Validate and stable-sort note events once, then expose logarithmic onset and\n * active-note lookups. Non-positive-duration notes may be retained for callers\n * that intentionally filter them later, but never count as sounding.\n *\n * @category Core\n */\nexport function createNoteEventIndex(\n  events: readonly NoteEvent[],\n  options: {\n    allowNonPositiveDuration?: boolean;\n    tieBreak?: OnsetTieBreak;\n    budget?: number;\n    /** What the events are, for the validation error message. */\n    name?: string;\n  } = {},\n): NoteEventIndex {\n  assertNoteEvents(events, options.name ?? 'note events', options);\n  const tieBreak = options.tieBreak ?? 'highest';\n  const notes = events\n    .map((note, originalIndex) => ({\n      note,\n      originalIndex,\n      endBeat: note.startBeat + note.durationBeat,\n    }))\n    .sort((a, b) => a.note.startBeat - b.note.startBeat || a.originalIndex - b.originalIndex);\n  // Built on the first `at` call rather than up front: several callers use this\n  // only to validate and sort, and never ask what sounds at a beat.\n  let prefixMaxEnd: number[] | undefined;\n  const maxEndUpTo = (index: number): number => {\n    if (prefixMaxEnd === undefined) {\n      const prefix: number[] = [];\n      let maxEnd = Number.NEGATIVE_INFINITY;\n      for (const indexed of notes) {\n        maxEnd = Math.max(maxEnd, indexed.endBeat);\n        prefix.push(maxEnd);\n      }\n      prefixMaxEnd = prefix;\n    }\n    return prefixMaxEnd[index] ?? Number.NEGATIVE_INFINITY;\n  };\n\n  return {\n    notes,\n    at(beat) {\n      let index = upperBound(notes, beat + EPS) - 1;\n      let best: IndexedNoteEvent | undefined;\n      while (index >= 0) {\n        if (maxEndUpTo(index) <= beat + EPS) {\n          break;\n        }\n        const indexed = notes[index];\n        index -= 1;\n        if (\n          indexed === undefined ||\n          indexed.note.durationBeat <= 0 ||\n          indexed.note.startBeat - EPS > beat ||\n          beat >= indexed.endBeat - EPS\n        ) {\n          continue;\n        }\n        if (best === undefined) {\n          best = indexed;\n          if (tieBreak === 'last') {\n            break;\n          }\n          continue;\n        }\n        // Only notes from the same onset compete: a later onset always wins.\n        if (Math.abs(indexed.note.startBeat - best.note.startBeat) >= EPS) {\n          break;\n        }\n        const higher = indexed.note.pitch > best.note.pitch;\n        if (tieBreak === 'highest' ? higher : !higher) {\n          best = indexed;\n        }\n      }\n      return best;\n    },\n    attacksAt(beat) {\n      // Only a sounding note attacks: a zero-length artefact must not make\n      // `attacksAt(b)` true on a beat where `at(b)` finds nothing.\n      let index = upperBound(notes, beat + EPS) - 1;\n      while (index >= 0) {\n        const candidate = notes[index];\n        if (candidate === undefined || Math.abs(candidate.note.startBeat - beat) >= EPS) {\n          return false;\n        }\n        if (candidate.note.durationBeat > 0) {\n          return true;\n        }\n        index -= 1;\n      }\n      return false;\n    },\n    onsetsBetween(startBeat, endBeat) {\n      const result: number[] = [];\n      let index = upperBound(notes, startBeat + EPS);\n      while (index < notes.length) {\n        const indexed = notes[index];\n        const onset = indexed?.note.startBeat;\n        if (indexed === undefined || onset === undefined || onset >= endBeat - EPS) {\n          break;\n        }\n        index += 1;\n        if (indexed.note.durationBeat <= 0) {\n          continue;\n        }\n        const previous = result[result.length - 1];\n        if (previous === undefined || Math.abs(previous - onset) >= EPS) {\n          result.push(onset);\n        }\n      }\n      return result;\n    },\n  };\n}\n"]}