@libraz/libcantus 0.9.1 → 0.9.3

package/src/analyze/arrange/tracks.ts

@@ -0,0 +1,312 @@
+/**
+ * Arrangement track-role analysis: a single harmony is inferred from every
+ * track's notes pooled together, each track is then analysed against that shared
+ * harmony, and notes that clash with the sounding chord are collected as
+ * conflicts.
+ */
+
+import { isStrongBeat, parseTimeSignature, type TimeSignature } from '../../core/meter/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import {
+  assertGenerationBudget,
+  assertNoteEvents,
+  assertTimeSignature,
+} from '../../core/validation/index.js';
+import {
+  evaluateSafety,
+  NoteSafety,
+  type SafetyProfile,
+  type VoiceSnapshot,
+} from '../../theory/safety/index.js';
+import {
+  type CadenceHit,
+  type ChordTimeline,
+  chordTimelineFromNotes,
+  detectCadences,
+} from '../timeline/index.js';
+import { type AnalyzedNote, analyzeVoice, type VoiceNote } from '../voice/index.js';
+import { covers, EPS, type PreparedTrack, poolNotes, prepareTracks } from './internal.js';
+
+/**
+ * The musical role a track plays in the arrangement.
+ *
+ * @category Arrangement & Analysis
+ */
+export type TrackRole = 'melody' | 'harmony' | 'bass' | 'other';
+
+/**
+ * One input track: its notes plus optional name and role.
+ *
+ * @category Arrangement & Analysis
+ */
+export type ArrangementTrack = {
+  name?: string;
+  role?: TrackRole;
+  notes: NoteEvent[];
+};
+
+/**
+ * A track after analysis: its resolved name, role, and per-note annotations.
+ *
+ * @category Arrangement & Analysis
+ */
+export type TrackAnalysis = {
+  name: string;
+  role: TrackRole;
+  /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
+  notes: AnalyzedNote[];
+};
+
+/**
+ * A note that clashes with the harmony sounding beneath it.
+ *
+ * @category Arrangement & Analysis
+ */
+export type Conflict = {
+  beat: number;
+  trackName: string;
+  pitch: number;
+  /** The clash severity: {@link NoteSafety.Warning} or {@link NoteSafety.Dissonant}. */
+  safety: NoteSafety;
+  /** {@link import('../safety/index.js').SafetyResult.reasons} bitmask. */
+  reasons: number;
+  /** Preferred stepwise resolution, when the safety evaluator provides one. */
+  resolveTo?: number;
+  /** Nearby fully safe replacement pitches, nearest first. */
+  suggestions?: number[];
+  rationale?: string;
+};
+
+/**
+ * The full result of {@link analyzeArrangement}.
+ *
+ * @category Arrangement & Analysis
+ */
+export type ArrangementAnalysis = {
+  key: KeyScale;
+  timeline: ChordTimeline;
+  segmentConfidence: number[];
+  cadences: CadenceHit[];
+  tracks: TrackAnalysis[];
+  /** Notes clashing with the sounding harmony, worst severity first. */
+  conflicts: Conflict[];
+};
+
+/**
+ * Options controlling {@link analyzeArrangement} and {@link tensionCurve}.
+ *
+ * @category Arrangement & Analysis
+ */
+export type ArrangementOptions = {
+  /** Key context; inferred from the pooled notes when omitted. */
+  key?: KeyScale;
+  /**
+   * Time signature; defaults to 4/4.
+   *
+   * @defaultValue `4/4`
+   */
+  ts?: TimeSignature;
+  /**
+   * Chord-slot length in beats; defaults to one bar of `ts`.
+   *
+   * @defaultValue one bar of `ts`
+   */
+  harmonicRhythm?: number;
+  /**
+   * Safety profile used for conflict detection; defaults to `pop`.
+   *
+   * @defaultValue `'pop'`
+   */
+  profile?: SafetyProfile;
+};
+
+/**
+ * Sounding pitches of every sub-voice at a beat, excluding one sub-voice.
+ *
+ * Only the sub-voice under analysis is excluded — sibling sub-voices of the
+ * same track are included, so dissonant clusters inside a single polyphonic
+ * track are still detected.
+ */
+function otherVoicesSounding(
+  prepared: PreparedTrack[],
+  excludeTrack: number,
+  excludeVoice: number,
+  beat: number,
+): VoiceSnapshot[] {
+  const out: VoiceSnapshot[] = [];
+  for (let t = 0; t < prepared.length; t += 1) {
+    const track = prepared[t];
+    if (!track) {
+      continue;
+    }
+    for (let v = 0; v < track.voices.length; v += 1) {
+      if (t === excludeTrack && v === excludeVoice) {
+        continue;
+      }
+      const subVoice = track.voices[v];
+      if (!subVoice) {
+        continue;
+      }
+      for (const note of subVoice.sounding) {
+        if (!covers(note, beat)) {
+          continue;
+        }
+        const snap: VoiceSnapshot = { pitch: note.pitch };
+        // Motion reasons compare one real transition shared by both voices.
+        // A voice attacking exactly here contributes its adjacent predecessor;
+        // a sustained voice contributes the same pitch (oblique motion).
+        const previous = Math.abs(note.startBeat - beat) <= EPS ? note.prevPitch : note.pitch;
+        if (previous !== undefined) {
+          snap.prevPitch = previous;
+        }
+        out.push(snap);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * The beats at which a note must be checked against the harmony: its onset,
+ * plus the onset of every later chord segment the note sustains across. Each
+ * crossed segment is visited exactly once (at its own start), so a boundary
+ * beat is never evaluated twice for the same note.
+ */
+function evaluationBeats(note: VoiceNote, timeline: ChordTimeline): number[] {
+  const noteEnd = note.startBeat + note.durationBeat;
+  const beats = [note.startBeat];
+  for (const segment of timeline.segments) {
+    if (segment.startBeat > note.startBeat + EPS && segment.startBeat < noteEnd - EPS) {
+      beats.push(segment.startBeat);
+    }
+  }
+  return beats;
+}
+
+/**
+ * Analyse a whole arrangement against a single inferred harmony.
+ *
+ * The chord timeline and key are inferred from the pooled notes of every track
+ * (see {@link chordTimelineFromNotes}); pooling all voices is robust even when
+ * roles are absent or a track doubles the harmony, so it is preferred over
+ * deriving the harmony from a subset. Zero- and negative-length notes never
+ * sound, so they are dropped at ingest and appear in neither the annotations
+ * nor the conflicts.
+ *
+ * Voice analysis assumes one monophonic voice at a time, so each track is
+ * first partitioned into monophonic sub-voices (a polyphonic block-chord track
+ * fans out into one sub-voice per simultaneous note; a monophonic track is
+ * unaffected). Each sub-voice is labelled note-by-note against the harmony
+ * with {@link analyzeVoice}, seeing every other sub-voice — including siblings
+ * within the same track — as its accompaniment. Every note is then re-checked
+ * with {@link evaluateSafety} at its onset and again at each chord change it
+ * sustains across, so a held note that clashes with a later chord is caught:
+ * evaluations that are not {@link NoteSafety.Safe} become conflicts, one per
+ * clashing beat, sorted worst severity first and then by beat.
+ *
+ * @param tracks The tracks to analyse.
+ * @param opts Analysis options; see {@link ArrangementOptions}.
+ * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
+ * @example
+ * ```ts
+ * import { analyzeArrangement } from '@libraz/libcantus';
+ * const melody = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 },
+ *   { pitch: 67, startBeat: 2, durationBeat: 2 },
+ * ];
+ * const { key, conflicts } = analyzeArrangement([{ role: 'melody', notes: melody }]);
+ * conflicts; // notes clashing with the inferred harmony, worst severity first
+ * ```
+ * @category Arrangement & Analysis
+ */
+export function analyzeArrangement(
+  tracks: ArrangementTrack[],
+  opts: ArrangementOptions = {},
+): ArrangementAnalysis {
+  const ts = opts.ts ?? parseTimeSignature('4/4');
+  assertTimeSignature(ts);
+  assertGenerationBudget(tracks.length, 'arrangement tracks');
+  for (let index = 0; index < tracks.length; index += 1) {
+    assertNoteEvents(tracks[index]?.notes ?? [], `tracks[${index}].notes`, {
+      allowNonPositiveDuration: true,
+    });
+  }
+  const profile: SafetyProfile = opts.profile ?? 'pop';
+  const pooled = poolNotes(tracks);
+
+  const { timeline, key, segmentConfidence } = chordTimelineFromNotes(pooled, {
+    key: opts.key,
+    ts,
+    harmonicRhythm: opts.harmonicRhythm,
+  });
+  const cadences = detectCadences(timeline, key);
+  const prepared = prepareTracks(tracks);
+
+  const trackAnalyses: TrackAnalysis[] = [];
+  const conflicts: Conflict[] = [];
+
+  for (let t = 0; t < prepared.length; t += 1) {
+    const track = prepared[t];
+    if (!track) {
+      continue;
+    }
+    const notes: AnalyzedNote[] = [];
+    for (let v = 0; v < track.voices.length; v += 1) {
+      const subVoice = track.voices[v];
+      if (!subVoice) {
+        continue;
+      }
+      notes.push(
+        ...analyzeVoice(subVoice.voice, timeline.at, key, (beat) =>
+          otherVoicesSounding(prepared, t, v, beat),
+        ),
+      );
+
+      for (let noteIndex = 0; noteIndex < subVoice.voice.length; noteIndex += 1) {
+        const note = subVoice.voice[noteIndex];
+        const preparedNote = subVoice.sounding[noteIndex];
+        if (note === undefined || preparedNote === undefined) {
+          continue;
+        }
+        for (const beat of evaluationBeats(note, timeline)) {
+          const atOnset = Math.abs(beat - note.startBeat) <= EPS;
+          const result = evaluateSafety({
+            profile,
+            candidatePitch: note.pitch,
+            prevPitch: atOnset ? preparedNote.prevPitch : note.pitch,
+            chord: timeline.at(beat),
+            key,
+            otherVoices: otherVoicesSounding(prepared, t, v, beat),
+            strongBeat: isStrongBeat(beat, ts),
+          });
+          if (result.safety !== NoteSafety.Safe) {
+            const conflict: Conflict = {
+              beat,
+              trackName: track.name,
+              pitch: note.pitch,
+              safety: result.safety,
+              reasons: result.reasons,
+            };
+            if (result.rationale !== undefined) {
+              conflict.rationale = result.rationale;
+            }
+            if (result.resolveTo !== undefined) {
+              conflict.resolveTo = result.resolveTo;
+            }
+            if (result.suggestions !== undefined) {
+              conflict.suggestions = [...result.suggestions];
+            }
+            conflicts.push(conflict);
+          }
+        }
+      }
+    }
+    // Sub-voice results interleave; restore the track's onset-then-pitch order.
+    notes.sort((a, b) => a.noteId - b.noteId);
+    trackAnalyses.push({ name: track.name, role: track.role, notes });
+  }
+
+  conflicts.sort((a, b) => b.safety - a.safety || a.beat - b.beat);
+
+  return { key, timeline, segmentConfidence, cadences, tracks: trackAnalyses, conflicts };
+}

package/src/{detect → analyze/detect}/index.ts

@@ -4,8 +4,10 @@
  * which only go name -> notes.
  */
 
-import type { Chord, ChordQuality } from '../chord/index.js';
-import { chordPitchClasses, chordQualities, makeChord } from '../chord/index.js';
+import type { KeyScale } from '../../core/types.js';
+import { assertFiniteNumber, assertGenerationBudget } from '../../core/validation/index.js';
+import type { Chord, ChordQuality } from '../../theory/chord/index.js';
+import { chordPitchClasses, chordQualities, makeChord } from '../../theory/chord/index.js';
 import {
   HARMONIC_MINOR_MASK,
   MAJOR_MASK,
@@ -13,8 +15,7 @@ import {
   majorKey,
   minorKey,
   NATURAL_MINOR_MASK,
-} from '../scale/index.js';
-import type { KeyScale } from '../types.js';
+} from '../../theory/scale/index.js';
 
 /**
  * A candidate chord interpretation of a pitch set.
@@ -30,12 +31,24 @@ export type ChordMatch = {
   extraPcs: number[];
   /** True when the input pitch-class set equals the chord exactly. */
   exact: boolean;
-  /** Inversion implied by the lowest note: 0 root position, 1 first, ... */
-  inversion: number;
+  /** Inversion implied by a known bass, or null for an unordered pitch-class set. */
+  inversion: number | null;
   /** Bass pitch class when inverted (the lowest note is not the root). */
   bassPc?: number;
 };
 
+/** Input interpretation for {@link detectChord} and {@link detectChordBest}. */
+export type DetectChordOptions = {
+  /**
+   * `midi` uses the numerically lowest pitch as bass; `pitchClass` treats the
+   * input as unordered. `auto` (default) selects pitch-class mode only when all
+   * values lie in 0..11.
+   */
+  input?: 'auto' | 'midi' | 'pitchClass';
+  /** Explicit bass pitch class, including for an unordered pitch-class set. */
+  bassPc?: number;
+};
+
 /**
  * A candidate key interpretation of a pitch-class set.
  *
@@ -58,6 +71,13 @@ function uniquePitchClasses(pitches: number[]): number[] {
   return [...new Set(pitches.map(pitchClass))].sort((a, b) => a - b);
 }
 
+function assertPitches(pitches: number[]): void {
+  assertGenerationBudget(pitches.length, 'detection pitches');
+  for (let index = 0; index < pitches.length; index += 1) {
+    assertFiniteNumber(pitches[index] ?? Number.NaN, `pitches[${index}]`);
+  }
+}
+
 /**
  * Identify chords matching a set of pitches.
  *
@@ -78,12 +98,25 @@ function uniquePitchClasses(pitches: number[]): number[] {
  * ```
  * @category Recognition
  */
-export function detectChord(pitches: number[]): ChordMatch[] {
+export function detectChord(pitches: number[], opts: DetectChordOptions = {}): ChordMatch[] {
+  assertPitches(pitches);
+  if (opts.bassPc !== undefined) assertFiniteNumber(opts.bassPc, 'bassPc');
   const input = uniquePitchClasses(pitches);
   if (input.length === 0) {
     return [];
   }
-  const bassPc = pitchClass(Math.min(...pitches));
+  const inputKind =
+    opts.input === undefined || opts.input === 'auto'
+      ? pitches.every((pitch) => Number.isInteger(pitch) && pitch >= 0 && pitch <= 11)
+        ? 'pitchClass'
+        : 'midi'
+      : opts.input;
+  const bassPc =
+    opts.bassPc !== undefined
+      ? pitchClass(opts.bassPc)
+      : inputKind === 'midi'
+        ? pitchClass(pitches.reduce((lowest, pitch) => Math.min(lowest, pitch), Infinity))
+        : undefined;
   const inputSet = new Set(input);
   const matches: ChordMatch[] = [];
   const qualities = chordQualities();
@@ -100,8 +133,11 @@ export function detectChord(pitches: number[]): ChordMatch[] {
         continue;
       }
       const extraPcs = input.filter((pc) => !toneSet.has(pc));
-      const bassIndex = chord.intervals.findIndex((iv) => pitchClass(rootPc + iv) === bassPc);
-      const inversion = bassIndex > 0 ? bassIndex : 0;
+      const bassIndex =
+        bassPc === undefined
+          ? -1
+          : chord.intervals.findIndex((iv) => pitchClass(rootPc + iv) === bassPc);
+      const inversion = bassPc === undefined ? null : bassIndex > 0 ? bassIndex : 0;
       const match: ChordMatch = {
         rootPc,
         quality,
@@ -110,7 +146,7 @@ export function detectChord(pitches: number[]): ChordMatch[] {
         exact: extraPcs.length === 0 && missingPcs.length === 0,
         inversion,
       };
-      if (inversion > 0) {
+      if (bassPc !== undefined && bassPc !== rootPc) {
         match.bassPc = bassPc;
       }
       matches.push(match);
@@ -146,8 +182,8 @@ export function detectChord(pitches: number[]): ChordMatch[] {
  * ```
  * @category Recognition
  */
-export function detectChordBest(pitches: number[]): Chord | null {
-  const best = detectChord(pitches)[0];
+export function detectChordBest(pitches: number[], opts: DetectChordOptions = {}): Chord | null {
+  const best = detectChord(pitches, opts)[0];
   if (!best) {
     return null;
   }
@@ -183,6 +219,7 @@ const MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MI
  * @category Recognition
  */
 export function detectKey(pitches: number[]): KeyMatch[] {
+  assertPitches(pitches);
   const input = uniquePitchClasses(pitches);
   if (input.length === 0) {
     return [];

package/src/analyze/functional/borrowed.ts

@@ -0,0 +1,84 @@
+/**
+ * Borrowed chords (modal interchange) and the Neapolitan.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+import type { KeyScale } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { HARMONIC_MINOR_MASK } from '../../theory/scale/index.js';
+import { isDiatonic, isMinorKey, parallelKey } from './function.js';
+import { isNeapolitan, mod12 } from './internal.js';
+
+/**
+ * The origin of a recognized non-diatonic chord, or null when none applies.
+ *
+ * @category Functional Harmony
+ */
+export type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
+
+/**
+ * In a minor key, whether a non-diatonic chord is explained by the harmonic
+ * minor scale on the same tonic (major V, V7, the raised-leading-tone viio).
+ * Such chords are in-key chromatic alterations, not modal interchange.
+ */
+function isHarmonicMinorAlteration(chord: Chord, key: KeyScale): boolean {
+  return (
+    isMinorKey(key) &&
+    isDiatonic(chord, { rootPc: mod12(key.rootPc), modeMask12: HARMONIC_MINOR_MASK })
+  );
+}
+
+/**
+ * Whether a chord is borrowed from the parallel mode (modal interchange).
+ *
+ * True when the chord is not diatonic to `key` but is diatonic to its
+ * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
+ * tonic and major IV in a minor key. Two non-diatonic families are excluded:
+ * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
+ * a minor key, chords explained by the harmonic minor scale (the major
+ * dominant and raised-leading-tone chords), which are in-key alterations
+ * rather than interchange even though they happen to fit the parallel major.
+ *
+ * @param chord The chord to test.
+ * @param key The prevailing key.
+ * @returns True if the chord is borrowed from the parallel mode.
+ * @category Functional Harmony
+ */
+export function isBorrowedChord(chord: Chord, key: KeyScale): boolean {
+  if (isDiatonic(chord, key)) {
+    return false;
+  }
+  if (isHarmonicMinorAlteration(chord, key)) {
+    return false;
+  }
+  return isDiatonic(chord, parallelKey(key));
+}
+
+/**
+ * Identify where a non-diatonic chord comes from.
+ *
+ * The Neapolitan (major triad on b2) is recognized first, since it sits
+ * outside both parallel modes; parallel-mode borrowing follows the
+ * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
+ * and unrecognized chromatic chords all yield null.
+ *
+ * @param chord The chord to classify.
+ * @param key The prevailing key.
+ * @returns The borrowing source, or null.
+ * @category Functional Harmony
+ */
+export function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource {
+  if (isDiatonic(chord, key)) {
+    return null;
+  }
+  if (isNeapolitan(chord, key)) {
+    return 'neapolitan';
+  }
+  if (isBorrowedChord(chord, key)) {
+    return isMinorKey(key) ? 'parallel-major' : 'parallel-minor';
+  }
+  return null;
+}

package/src/analyze/functional/cadence.ts

@@ -0,0 +1,66 @@
+/**
+ * Cadence detection between two successive chords.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+import type { KeyScale } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { isMinorKey } from './function.js';
+import { mod12 } from './internal.js';
+
+/**
+ * A recognized cadence type, or null when a chord pair forms none.
+ *
+ * @category Functional Harmony
+ */
+export type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
+
+/**
+ * Classify the cadence formed by moving from one chord to the next.
+ *
+ * - authentic: V (dominant a fifth above the tonic) to I
+ * - plagal: IV (a fourth above the tonic) to I
+ * - deceptive: V to the submediant (diatonic vi or borrowed bVI in major, VI in
+ *   minor)
+ * - half: any chord other than the dominant itself to V
+ *
+ * A static V-to-V repeat with no root motion is not a cadence and yields null.
+ *
+ * @param from The penultimate chord.
+ * @param to The final chord.
+ * @param key The prevailing key.
+ * @returns The cadence type, or null.
+ * @example
+ * ```ts
+ * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
+ * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'
+ * ```
+ * @category Functional Harmony
+ */
+export function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence {
+  const tonic = mod12(key.rootPc);
+  const fromOffset = mod12(from.rootPc - tonic);
+  const toOffset = mod12(to.rootPc - tonic);
+  // Deceptive targets: the diatonic submediant (vi at offset 9 in major, VI at
+  // offset 8 in minor) plus, in a major key, the borrowed flat-submediant bVI
+  // at offset 8.
+  const deceptiveTargets = isMinorKey(key) ? [8] : [8, 9];
+  if (fromOffset === 7 && toOffset === 0) {
+    return 'authentic';
+  }
+  if (fromOffset === 5 && toOffset === 0) {
+    return 'plagal';
+  }
+  if (fromOffset === 7 && deceptiveTargets.includes(toOffset)) {
+    return 'deceptive';
+  }
+  // A move to the dominant is a half cadence, but a no-root-motion V-to-V repeat
+  // is not a cadence at all.
+  if (toOffset === 7 && fromOffset !== 7) {
+    return 'half';
+  }
+  return null;
+}