@libraz/libcantus 0.9.0 → 0.9.2

package/src/analyze/arrange/tracks.ts

@@ -0,0 +1,279 @@
+/**
+ * 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 {
+  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;
+  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 };
+        if (note.prevPitch !== undefined) {
+          snap.prevPitch = note.prevPitch;
+        }
+        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');
+  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 (const note of subVoice.voice) {
+        for (const beat of evaluationBeats(note, timeline)) {
+          const result = evaluateSafety({
+            profile,
+            candidatePitch: 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;
+            }
+            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,12 +4,23 @@
  * which only go name -> notes.
  */
 
-import type { Chord, ChordQuality } from '../chord/index.js';
-import { chordPitchClasses, chordQualities, makeChord } from '../chord/index.js';
-import { majorKey, minorKey } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
+import type { KeyScale } from '../../core/types.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,
+  MELODIC_MINOR_MASK,
+  majorKey,
+  minorKey,
+  NATURAL_MINOR_MASK,
+} from '../../theory/scale/index.js';
 
-/** A candidate chord interpretation of a pitch set. */
+/**
+ * A candidate chord interpretation of a pitch set.
+ *
+ * @category Recognition
+ */
 export type ChordMatch = {
   rootPc: number;
   quality: ChordQuality;
@@ -25,7 +36,11 @@ export type ChordMatch = {
   bassPc?: number;
 };
 
-/** A candidate key interpretation of a pitch-class set. */
+/**
+ * A candidate key interpretation of a pitch-class set.
+ *
+ * @category Recognition
+ */
 export type KeyMatch = {
   key: KeyScale;
   mode: 'major' | 'minor';
@@ -55,6 +70,13 @@ function uniquePitchClasses(pitches: number[]): number[] {
  *
  * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).
  * @returns Ranked chord interpretations (may be empty).
+ * @example
+ * ```ts
+ * import { detectChord } from '@libraz/libcantus';
+ * const matches = detectChord([60, 64, 67]); // C E G
+ * matches[0]; // { rootPc: 0, quality: 'maj', exact: true, ... }
+ * ```
+ * @category Recognition
  */
 export function detectChord(pitches: number[]): ChordMatch[] {
   const input = uniquePitchClasses(pitches);
@@ -85,7 +107,7 @@ export function detectChord(pitches: number[]): ChordMatch[] {
         quality,
         missingPcs,
         extraPcs,
-        exact: extraPcs.length === 0,
+        exact: extraPcs.length === 0 && missingPcs.length === 0,
         inversion,
       };
       if (inversion > 0) {
@@ -117,6 +139,12 @@ export function detectChord(pitches: number[]): ChordMatch[] {
  *
  * @param pitches MIDI pitches or bare pitch classes.
  * @returns The top-ranked chord, or null when nothing matches.
+ * @example
+ * ```ts
+ * import { detectChordBest } from '@libraz/libcantus';
+ * detectChordBest([60, 64, 67]); // C major triad: { rootPc: 0, quality: 'maj', ... }
+ * ```
+ * @category Recognition
  */
 export function detectChordBest(pitches: number[]): Chord | null {
   const best = detectChord(pitches)[0];
@@ -126,47 +154,78 @@ export function detectChordBest(pitches: number[]): Chord | null {
   return makeChord(best.rootPc, best.quality, best.bassPc);
 }
 
+/**
+ * Minor-scale variants scored for each minor-key candidate. Scoring against all
+ * three lets the raised sixth and seventh (e.g. the leading tone G# in A minor)
+ * count toward their own tonic instead of only penalizing it.
+ */
+const MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MINOR_MASK];
+
 /**
  * Rank major and minor keys by how well they contain a set of pitch classes.
  *
  * The tonic is weighted so that, among equally-fitting keys, the one whose root
- * appears in the input is preferred. Returns all 24 keys ranked best-first.
+ * appears in the input is preferred. Minor candidates are scored against the
+ * natural, harmonic, and melodic minor variants and keep the best of the three,
+ * so a minor cadence containing the leading tone still resolves to its own
+ * tonic; the returned key is always the natural-minor scale. Returns all 24
+ * keys ranked best-first, or an empty array for an empty input (mirroring
+ * {@link detectChord}).
  *
  * @param pitches MIDI pitches or bare pitch classes.
- * @returns Ranked key interpretations.
+ * @returns Ranked key interpretations (empty for an empty input).
+ * @example
+ * ```ts
+ * import { detectKey } from '@libraz/libcantus';
+ * const keys = detectKey([60, 62, 64, 65, 67, 69, 71]); // C major scale
+ * keys[0].mode; // 'major', with keys[0].key.rootPc === 0
+ * ```
+ * @category Recognition
  */
 export function detectKey(pitches: number[]): KeyMatch[] {
   const input = uniquePitchClasses(pitches);
+  if (input.length === 0) {
+    return [];
+  }
   const counts = new Map<number, number>();
   for (const pc of pitches.map(pitchClass)) {
     counts.set(pc, (counts.get(pc) ?? 0) + 1);
   }
-  const total = pitches.length || 1;
+  const total = pitches.length;
   const results: (KeyMatch & { score: number })[] = [];
   for (let tonic = 0; tonic < 12; tonic += 1) {
     for (const mode of ['major', 'minor'] as const) {
       const key = mode === 'major' ? majorKey(tonic) : minorKey(tonic);
+      const masks = mode === 'major' ? [MAJOR_MASK] : MINOR_MASK_VARIANTS;
+      // Score each scale variant and keep the best; ties keep the earlier
+      // (more diatonic) variant.
       let inScale = 0;
-      let weighted = 0;
-      for (const pc of input) {
-        const offset = (pc - tonic + 12) % 12;
-        if ((key.modeMask12 >> offset) & 1) {
-          inScale += 1;
+      let weighted = Number.NEGATIVE_INFINITY;
+      for (const mask of masks) {
+        let variantInScale = 0;
+        let variantWeighted = 0;
+        for (const pc of input) {
+          const offset = (pc - tonic + 12) % 12;
+          if ((mask >> offset) & 1) {
+            variantInScale += 1;
+          }
         }
-      }
-      for (const [pc, count] of counts) {
-        const offset = (pc - tonic + 12) % 12;
-        if ((key.modeMask12 >> offset) & 1) {
-          weighted += count;
+        for (const [pc, count] of counts) {
+          const offset = (pc - tonic + 12) % 12;
+          if ((mask >> offset) & 1) {
+            variantWeighted += count;
+          }
         }
-        if (pc === tonic) {
-          weighted += count * 0.5;
+        if (variantWeighted > weighted) {
+          weighted = variantWeighted;
+          inScale = variantInScale;
         }
       }
+      weighted += (counts.get(tonic) ?? 0) * 0.5;
       results.push({
         key,
         mode,
-        fit: input.length === 0 ? 0 : inScale / input.length,
+        fit: inScale / input.length,
         score: weighted / total,
       });
     }

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;
+}