@libraz/libcantus 0.9.0 → 0.9.2

package/dist/types-MGP29r3t.d.cts

@@ -0,0 +1,30 @@
+/**
+ * A key/scale definition anchored on a root pitch class.
+ *
+ * `modeMask12` is a 12-bit mask where bit `n` set means the pitch class
+ * `(rootPc + n) % 12` belongs to the scale. Bit 0 (the root) is always set;
+ * {@link maskFromOffsets} enforces this so the root is always a scale tone.
+ */
+type KeyScale = {
+    rootPc: number;
+    modeMask12: number;
+};
+/**
+ * A single sounding note on a beat-indexed timeline: an absolute MIDI pitch, an
+ * onset and duration measured in quarter-note beats, and an optional MIDI
+ * velocity. This is the library-wide interchange shape for note events read
+ * from or written to a DAW/MIDI track; the harmonizer's `MelodyNote` and the
+ * analysis `VoiceNote` are specializations of it.
+ */
+type NoteEvent = {
+    /** MIDI pitch (middle C = 60). */
+    pitch: number;
+    /** Onset in quarter-note beats, absolute from the start of the timeline. */
+    startBeat: number;
+    /** Duration in quarter-note beats. */
+    durationBeat: number;
+    /** MIDI velocity in [0, 127], when known. */
+    velocity?: number;
+};
+
+export type { KeyScale as K, NoteEvent as N };

package/dist/types-MGP29r3t.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A key/scale definition anchored on a root pitch class.
+ *
+ * `modeMask12` is a 12-bit mask where bit `n` set means the pitch class
+ * `(rootPc + n) % 12` belongs to the scale. Bit 0 (the root) is always set;
+ * {@link maskFromOffsets} enforces this so the root is always a scale tone.
+ */
+type KeyScale = {
+    rootPc: number;
+    modeMask12: number;
+};
+/**
+ * A single sounding note on a beat-indexed timeline: an absolute MIDI pitch, an
+ * onset and duration measured in quarter-note beats, and an optional MIDI
+ * velocity. This is the library-wide interchange shape for note events read
+ * from or written to a DAW/MIDI track; the harmonizer's `MelodyNote` and the
+ * analysis `VoiceNote` are specializations of it.
+ */
+type NoteEvent = {
+    /** MIDI pitch (middle C = 60). */
+    pitch: number;
+    /** Onset in quarter-note beats, absolute from the start of the timeline. */
+    startBeat: number;
+    /** Duration in quarter-note beats. */
+    durationBeat: number;
+    /** MIDI velocity in [0, 127], when known. */
+    velocity?: number;
+};
+
+export type { KeyScale as K, NoteEvent as N };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libcantus",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Pure-TypeScript music-theory and composition primitives (intervals, scales, chords).",
   "type": "module",
   "license": "Apache-2.0",
@@ -38,6 +38,31 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
+    },
+    "./theory": {
+      "types": "./dist/theory/index.d.ts",
+      "import": "./dist/theory/index.js",
+      "require": "./dist/theory/index.cjs"
+    },
+    "./analyze": {
+      "types": "./dist/analyze/index.d.ts",
+      "import": "./dist/analyze/index.js",
+      "require": "./dist/analyze/index.cjs"
+    },
+    "./generate": {
+      "types": "./dist/generate/index.d.ts",
+      "import": "./dist/generate/index.js",
+      "require": "./dist/generate/index.cjs"
+    },
+    "./model": {
+      "types": "./dist/model/index.d.ts",
+      "import": "./dist/model/index.js",
+      "require": "./dist/model/index.cjs"
     }
   },
   "files": [
@@ -58,13 +83,18 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "docs": "typedoc",
     "prepare": "[ -d node_modules/typescript ] && tsup || true",
     "prepublishOnly": "yarn build"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
+    "@libraz/typedoc-theme": "^0.1.1",
     "@vitest/coverage-v8": "4.1.9",
     "tsup": "8.5.1",
+    "typedoc": "0.28.20",
+    "typedoc-plugin-extras": "4.0.1",
+    "typedoc-plugin-mdn-links": "5.1.1",
     "typescript": "6.0.3",
     "vitest": "4.1.9"
   }

package/src/analyze/arrange/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Arrangement analysis: the capstone that ties the timeline, per-voice analysis,
+ * functional harmony, and safety modules together for a whole multi-track piece.
+ *
+ * A chord timeline and key are inferred once from every track's notes pooled
+ * together; each track is then analysed against that shared harmony, notes that
+ * clash with the sounding chord are collected as conflicts, and a coarse tension
+ * curve is sampled across the piece.
+ */
+
+export type { TensionPoint } from './tension.js';
+export { tensionCurve } from './tension.js';
+export type {
+  ArrangementAnalysis,
+  ArrangementOptions,
+  ArrangementTrack,
+  Conflict,
+  TrackAnalysis,
+  TrackRole,
+} from './tracks.js';
+export { analyzeArrangement } from './tracks.js';

package/src/analyze/arrange/internal.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared helpers for the arrangement-analysis modules: pooling every track's
+ * sounding notes and partitioning a track into monophonic sub-voices, plus the
+ * small geometric primitives both the track-role and tension passes rely on.
+ */
+
+import type { NoteEvent } from '../../core/types.js';
+import type { VoiceNote } from '../voice/index.js';
+import type { ArrangementTrack, TrackRole } from './tracks.js';
+
+/** Float tolerance for beat boundary comparisons. */
+export const EPS = 1e-9;
+
+/** A note with the pitch that immediately preceded it in the same sub-voice. */
+export type PreparedNote = {
+  pitch: number;
+  prevPitch?: number;
+  startBeat: number;
+  endBeat: number;
+};
+
+/** One monophonic sub-voice of a track: ordered notes plus sounding spans. */
+export type PreparedVoice = {
+  /** The sub-voice's notes in time order, each with a stable id. */
+  voice: VoiceNote[];
+  /** The same notes as sounding spans, each carrying its predecessor's pitch. */
+  sounding: PreparedNote[];
+};
+
+/** A track prepared for analysis: resolved metadata plus monophonic sub-voices. */
+export type PreparedTrack = {
+  name: string;
+  role: TrackRole;
+  /**
+   * The track's notes partitioned into monophonic sub-voices. Voice analysis
+   * assumes one note at a time, so a polyphonic track (e.g. a 'harmony' track
+   * playing block chords) is split here; a monophonic track yields exactly one
+   * sub-voice.
+   */
+  voices: PreparedVoice[];
+};
+
+/** Whether a sounding span `[start, end)` covers a beat. */
+export function covers(note: PreparedNote, beat: number): boolean {
+  return beat >= note.startBeat - EPS && beat < note.endBeat - EPS;
+}
+
+/**
+ * Every sounding note of every track pooled into one flat list. Zero- and
+ * negative-length notes never sound, so they are dropped here (matching the
+ * chord-inference ingest in the timeline module).
+ */
+export function poolNotes(tracks: ArrangementTrack[]): NoteEvent[] {
+  const notes: NoteEvent[] = [];
+  for (const track of tracks) {
+    for (const note of track.notes) {
+      if (note.durationBeat > 0) {
+        notes.push(note);
+      }
+    }
+  }
+  return notes;
+}
+
+/**
+ * Split a track's ordered notes into monophonic sub-voices.
+ *
+ * Greedy lane assignment: each note joins the first sub-voice that is free at
+ * its onset (its last note has ended), otherwise it opens a new sub-voice. A
+ * monophonic track therefore stays a single sub-voice, while block chords fan
+ * out into one sub-voice per simultaneous note, keeping every sub-voice's
+ * note-to-note adjacency genuinely melodic.
+ */
+function splitIntoSubVoices(ordered: VoiceNote[]): VoiceNote[][] {
+  const lanes: VoiceNote[][] = [];
+  for (const note of ordered) {
+    const lane = lanes.find((candidate) => {
+      const last = candidate[candidate.length - 1];
+      return last !== undefined && last.startBeat + last.durationBeat <= note.startBeat + EPS;
+    });
+    if (lane) {
+      lane.push(note);
+    } else {
+      lanes.push([note]);
+    }
+  }
+  return lanes;
+}
+
+/**
+ * Resolve each track's metadata and derive its monophonic sub-voices.
+ *
+ * Notes are sorted by onset, then pitch, so ordering is deterministic, and ids
+ * are assigned in that order. Zero- and negative-length notes never sound and
+ * are dropped at ingest. Each track is then partitioned into monophonic
+ * sub-voices (see {@link splitIntoSubVoices}); the predecessor pitch used for
+ * suspension and parallel detection is the previous note of the same sub-voice,
+ * never a simultaneous chord member.
+ */
+export function prepareTracks(tracks: ArrangementTrack[]): PreparedTrack[] {
+  let nextId = 0;
+  return tracks.map((track, index) => {
+    const ordered: VoiceNote[] = track.notes
+      .filter((note) => note.durationBeat > 0)
+      .sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch)
+      .map((note) => ({ ...note, id: nextId++ }));
+    const voices: PreparedVoice[] = splitIntoSubVoices(ordered).map((voice) => ({
+      voice,
+      sounding: voice.map((note, i) => {
+        const prev = i > 0 ? voice[i - 1] : undefined;
+        return {
+          pitch: note.pitch,
+          prevPitch: prev?.pitch,
+          startBeat: note.startBeat,
+          endBeat: note.startBeat + note.durationBeat,
+        };
+      }),
+    }));
+    return {
+      name: track.name ?? `track ${index + 1}`,
+      role: track.role ?? 'other',
+      voices,
+    };
+  });
+}

package/src/analyze/arrange/tension.ts

@@ -0,0 +1,187 @@
+/**
+ * Arrangement tension analysis: a coarse harmonic-tension curve sampled at
+ * regular beats across a whole multi-track piece, combining the sounding
+ * chord's harmonic function, the dissonance of the sounding notes, and their
+ * registral span into a single normalized reading.
+ */
+
+import { isStrongBeat, parseTimeSignature, type TimeSignature } from '../../core/meter/index.js';
+import type { KeyScale } from '../../core/types.js';
+import { chordPitchClasses } from '../../theory/chord/index.js';
+import { evaluateSafety, NoteSafety, type SafetyProfile } from '../../theory/safety/index.js';
+import { functionOf } from '../functional/index.js';
+import { type ChordTimeline, chordTimelineFromNotes } from '../timeline/index.js';
+import { covers, EPS, type PreparedTrack, poolNotes, prepareTracks } from './internal.js';
+import type { ArrangementOptions, ArrangementTrack } from './tracks.js';
+
+/**
+ * A tension reading sampled at a beat.
+ *
+ * @category Arrangement & Analysis
+ */
+export type TensionPoint = {
+  beat: number;
+  /** Combined tension in [0, 1]. */
+  tension: number;
+};
+
+/** Tension contributed by the sounding chord's harmonic function. */
+const FUNCTION_TENSION: Record<'tonic' | 'subdominant' | 'dominant', number> = {
+  tonic: 0,
+  subdominant: 0.5,
+  dominant: 1,
+};
+
+/** Weight of the harmonic-function term in the combined tension score. */
+const FUNCTION_WEIGHT = 0.5;
+/** Weight of the non-chord-tone / dissonance term. */
+const DISSONANCE_WEIGHT = 0.35;
+/** Weight of the registral-span term. */
+const SPAN_WEIGHT = 0.15;
+/** Pitch span, in semitones, that saturates the span term. */
+const SPAN_SATURATION = 24;
+
+/** Reduce a pitch to a pitch class in [0, 11]. */
+function pitchClass(pitch: number): number {
+  return ((Math.trunc(pitch) % 12) + 12) % 12;
+}
+
+/** Clamp a value into [0, 1]. */
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+/**
+ * Sample the harmonic tension of an arrangement at regular beats.
+ *
+ * At each sample beat the tension combines three normalized terms:
+ *  - the sounding chord's harmonic function (dominant `1`, subdominant `0.5`,
+ *    tonic or no chord `0`), weighted {@link FUNCTION_WEIGHT};
+ *  - the dissonance of the sounding notes — the larger of the share of sounding
+ *    pitches that are not chord tones and the share that {@link evaluateSafety}
+ *    rates {@link NoteSafety.Dissonant} — weighted {@link DISSONANCE_WEIGHT};
+ *  - the registral span of the sounding notes, saturating at
+ *    {@link SPAN_SATURATION} semitones, weighted {@link SPAN_WEIGHT}.
+ *
+ * The weighted sum is clamped to [0, 1]. The harmony is inferred from all tracks
+ * pooled together, so the result is deterministic and self-contained.
+ *
+ * @param tracks The tracks to sample.
+ * @param opts Analysis options plus an optional `step` (default one beat).
+ * @returns One {@link TensionPoint} per sampled beat, in beat order.
+ * @throws If `step` is not positive.
+ * @example
+ * ```ts
+ * import { tensionCurve } from '@libraz/libcantus';
+ * const notes = [{ pitch: 60, startBeat: 0, durationBeat: 4 }];
+ * const curve = tensionCurve([{ notes }], { step: 1 });
+ * curve; // one { beat, tension } sample per beat, in beat order
+ * ```
+ * @category Arrangement & Analysis
+ */
+export function tensionCurve(
+  tracks: ArrangementTrack[],
+  opts: ArrangementOptions & { step?: number } = {},
+): TensionPoint[] {
+  const ts = opts.ts ?? parseTimeSignature('4/4');
+  const profile: SafetyProfile = opts.profile ?? 'pop';
+  const step = opts.step ?? 1;
+  if (!(step > 0)) {
+    throw new Error(`Invalid tension sampling step: ${step}`);
+  }
+
+  const pooled = poolNotes(tracks);
+  const totalBeats = pooled.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
+  const { timeline, key } = chordTimelineFromNotes(pooled, {
+    key: opts.key,
+    ts,
+    harmonicRhythm: opts.harmonicRhythm,
+  });
+
+  const prepared = prepareTracks(tracks);
+  const points: TensionPoint[] = [];
+  const sampleCount = Math.max(0, Math.ceil(totalBeats / step - EPS));
+  for (let i = 0; i < sampleCount; i += 1) {
+    const beat = i * step;
+    points.push({ beat, tension: sampleTension(prepared, timeline, key, ts, profile, beat) });
+  }
+  return points;
+}
+
+/** All sounding notes across every track at a beat, tagged with their track. */
+function allSounding(prepared: PreparedTrack[], beat: number): { pitch: number; track: number }[] {
+  const out: { pitch: number; track: number }[] = [];
+  for (let t = 0; t < prepared.length; t += 1) {
+    const track = prepared[t];
+    if (!track) {
+      continue;
+    }
+    for (const subVoice of track.voices) {
+      for (const note of subVoice.sounding) {
+        if (covers(note, beat)) {
+          out.push({ pitch: note.pitch, track: t });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Combine the harmonic, dissonance, and span terms at one sample beat. */
+function sampleTension(
+  prepared: PreparedTrack[],
+  timeline: ChordTimeline,
+  key: KeyScale,
+  ts: TimeSignature,
+  profile: SafetyProfile,
+  beat: number,
+): number {
+  const sounding = allSounding(prepared, beat);
+  if (sounding.length === 0) {
+    return 0;
+  }
+  const chord = timeline.at(beat);
+  const functionScore = chord ? FUNCTION_TENSION[functionOf(chord, key)] : 0;
+
+  const chordPcs = chord ? new Set(chordPitchClasses(chord)) : null;
+  const strongBeat = isStrongBeat(beat, ts);
+  let nonChord = 0;
+  let dissonant = 0;
+  for (let i = 0; i < sounding.length; i += 1) {
+    const voice = sounding[i];
+    if (!voice) {
+      continue;
+    }
+    // Non-chord-tone share only applies when a chord is sounding; at a timeline
+    // gap there is no reference harmony, so vertical dissonance alone drives the
+    // dissonance term (the chord function term is already 0 there).
+    if (chordPcs && !chordPcs.has(pitchClass(voice.pitch))) {
+      nonChord += 1;
+    }
+    const others = sounding.filter((_, j) => j !== i).map((s) => ({ pitch: s.pitch }));
+    const result = evaluateSafety({
+      profile,
+      candidatePitch: voice.pitch,
+      chord,
+      key,
+      otherVoices: others,
+      strongBeat,
+    });
+    if (result.safety === NoteSafety.Dissonant) {
+      dissonant += 1;
+    }
+  }
+  const dissonanceScore = Math.max(nonChord, dissonant) / sounding.length;
+
+  let low = Number.POSITIVE_INFINITY;
+  let high = Number.NEGATIVE_INFINITY;
+  for (const voice of sounding) {
+    low = Math.min(low, voice.pitch);
+    high = Math.max(high, voice.pitch);
+  }
+  const spanScore = Math.min(1, (high - low) / SPAN_SATURATION);
+
+  return clamp01(
+    FUNCTION_WEIGHT * functionScore + DISSONANCE_WEIGHT * dissonanceScore + SPAN_WEIGHT * spanScore,
+  );
+}