@libraz/libcantus 0.9.2 → 0.9.3

package/dist/analyze/index.d.cts

@@ -1,10 +1,11 @@
 import { T as TimeSignature } from '../index-Cl7mhOFM.cjs';
 import { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.cjs';
-import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-DZ1M21do.cjs';
-import { b as ChordTimeline, C as CadenceHit } from '../index-D_ZTUNKp.cjs';
-export { a as ChordSegment, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from '../index-D_ZTUNKp.cjs';
-import { C as Chord, a as ChordQuality } from '../index-BOBXBNwP.cjs';
-export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from '../function-r2sh-jOO.cjs';
+import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-CxqBQtH1.cjs';
+import { b as ChordTimeline, C as CadenceHit } from '../index-CpOsP1y9.cjs';
+export { a as ChordSegment, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from '../index-CpOsP1y9.cjs';
+import { C as Chord } from '../index-BNlGP86A.cjs';
+export { C as ChordMatch, D as DetectChordOptions, K as KeyMatch, d as detectChord, a as detectChordBest, b as detectKey } from '../index-CnZCo29u.cjs';
+export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from '../function-DYt4iKsn.cjs';
 
 /**
  * Roman-numeral parsing and formatting.
@@ -203,6 +204,10 @@ type Conflict = {
     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;
 };
 /**
@@ -333,97 +338,4 @@ declare function tensionCurve(tracks: ArrangementTrack[], opts?: ArrangementOpti
     step?: number;
 }): TensionPoint[];
 
-/**
- * Recognition: infer a chord name from a set of pitches, or a key from a set of
- * pitch classes. This is the inverse direction of the chord/scale builders,
- * which only go name -> notes.
- */
-
-/**
- * A candidate chord interpretation of a pitch set.
- *
- * @category Recognition
- */
-type ChordMatch = {
-    rootPc: number;
-    quality: ChordQuality;
-    /** Chord tones absent from the input (an incomplete voicing). */
-    missingPcs: number[];
-    /** Input pitch classes not belonging to the chord. */
-    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;
-    /** Bass pitch class when inverted (the lowest note is not the root). */
-    bassPc?: number;
-};
-/**
- * A candidate key interpretation of a pitch-class set.
- *
- * @category Recognition
- */
-type KeyMatch = {
-    key: KeyScale;
-    mode: 'major' | 'minor';
-    /** Fraction of input pitch classes that are in the scale, in [0, 1]. */
-    fit: number;
-};
-/**
- * Identify chords matching a set of pitches.
- *
- * Every input pitch class is tried as a root against every known chord quality.
- * A match is reported when all of the chord's tones are present in the input, or
- * when the only absent tone is the perfect fifth (a common omission in shell
- * voicings); matches are ranked best-first by fewest extra notes, then fewest
- * missing notes, then most specific (largest) chord. An exact match (no extras,
- * no missing) is flagged and ranked first.
- *
- * @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
- */
-declare function detectChord(pitches: number[]): ChordMatch[];
-/**
- * The single best chord interpretation of a pitch set, or null if none.
- *
- * @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
- */
-declare function detectChordBest(pitches: number[]): Chord | null;
-/**
- * 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. 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 (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
- */
-declare function detectKey(pitches: number[]): KeyMatch[];
-
-export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, type ChordMatch, ChordTimeline, type Conflict, type KeyMatch, type TensionPoint, type TheoryLabel, type TrackAnalysis, type TrackRole, type VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, detectChord, detectChordBest, detectKey, romanToChord, tensionCurve };
+export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, ChordTimeline, type Conflict, type TensionPoint, type TheoryLabel, type TrackAnalysis, type TrackRole, type VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, romanToChord, tensionCurve };

package/dist/analyze/index.d.ts

@@ -1,10 +1,11 @@
 import { T as TimeSignature } from '../index-Cl7mhOFM.js';
 import { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.js';
-import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-BreoJRw0.js';
-import { b as ChordTimeline, C as CadenceHit } from '../index-BMPxwjwV.js';
-export { a as ChordSegment, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from '../index-BMPxwjwV.js';
-import { C as Chord, a as ChordQuality } from '../index-CM5W4rcm.js';
-export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from '../function-2bJW1Zp_.js';
+import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-Jc0Ryi79.js';
+import { b as ChordTimeline, C as CadenceHit } from '../index-DxvARIP2.js';
+export { a as ChordSegment, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from '../index-DxvARIP2.js';
+import { C as Chord } from '../index-Bt4tOUD9.js';
+export { C as ChordMatch, D as DetectChordOptions, K as KeyMatch, d as detectChord, a as detectChordBest, b as detectKey } from '../index-JnF4v9bx.js';
+export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from '../function-DVH4Eusr.js';
 
 /**
  * Roman-numeral parsing and formatting.
@@ -203,6 +204,10 @@ type Conflict = {
     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;
 };
 /**
@@ -333,97 +338,4 @@ declare function tensionCurve(tracks: ArrangementTrack[], opts?: ArrangementOpti
     step?: number;
 }): TensionPoint[];
 
-/**
- * Recognition: infer a chord name from a set of pitches, or a key from a set of
- * pitch classes. This is the inverse direction of the chord/scale builders,
- * which only go name -> notes.
- */
-
-/**
- * A candidate chord interpretation of a pitch set.
- *
- * @category Recognition
- */
-type ChordMatch = {
-    rootPc: number;
-    quality: ChordQuality;
-    /** Chord tones absent from the input (an incomplete voicing). */
-    missingPcs: number[];
-    /** Input pitch classes not belonging to the chord. */
-    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;
-    /** Bass pitch class when inverted (the lowest note is not the root). */
-    bassPc?: number;
-};
-/**
- * A candidate key interpretation of a pitch-class set.
- *
- * @category Recognition
- */
-type KeyMatch = {
-    key: KeyScale;
-    mode: 'major' | 'minor';
-    /** Fraction of input pitch classes that are in the scale, in [0, 1]. */
-    fit: number;
-};
-/**
- * Identify chords matching a set of pitches.
- *
- * Every input pitch class is tried as a root against every known chord quality.
- * A match is reported when all of the chord's tones are present in the input, or
- * when the only absent tone is the perfect fifth (a common omission in shell
- * voicings); matches are ranked best-first by fewest extra notes, then fewest
- * missing notes, then most specific (largest) chord. An exact match (no extras,
- * no missing) is flagged and ranked first.
- *
- * @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
- */
-declare function detectChord(pitches: number[]): ChordMatch[];
-/**
- * The single best chord interpretation of a pitch set, or null if none.
- *
- * @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
- */
-declare function detectChordBest(pitches: number[]): Chord | null;
-/**
- * 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. 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 (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
- */
-declare function detectKey(pitches: number[]): KeyMatch[];
-
-export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, type ChordMatch, ChordTimeline, type Conflict, type KeyMatch, type TensionPoint, type TheoryLabel, type TrackAnalysis, type TrackRole, type VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, detectChord, detectChordBest, detectKey, romanToChord, tensionCurve };
+export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, ChordTimeline, type Conflict, type TensionPoint, type TheoryLabel, type TrackAnalysis, type TrackRole, type VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, romanToChord, tensionCurve };

package/dist/analyze/index.js

@@ -5,8 +5,8 @@ import {
   chordTimelineFromNotes,
   detectCadences,
   tensionCurve
-} from "../chunk-5HTNMQW4.js";
-import "../chunk-MSWFZF7J.js";
+} from "../chunk-GOAW4VYL.js";
+import "../chunk-I5R7ZBJS.js";
 import {
   analyzeChord,
   borrowedSource,
@@ -22,10 +22,10 @@ import {
   parallelKey,
   romanToChord,
   secondaryDominant
-} from "../chunk-LN7ZZMD2.js";
-import "../chunk-A4532ZFR.js";
-import "../chunk-7Y7WF64D.js";
-import "../chunk-CCBLVAPK.js";
+} from "../chunk-CHMXELDS.js";
+import "../chunk-EH6EM37U.js";
+import "../chunk-MIWO425M.js";
+import "../chunk-FBQK3ZQN.js";
 export {
   analyzeArrangement,
   analyzeChord,

package/dist/chunk-2ZWMSJH6.js

@@ -0,0 +1,30 @@
+import {
+  chordToneRole
+} from "./chunk-MIWO425M.js";
+
+// src/theory/harmony/index.ts
+function roleOf(pitch, chord, chordId = 0) {
+  const interval = ((Math.trunc(pitch) - chord.rootPc) % 12 + 12) % 12;
+  const tones = new Set(chord.intervals.map((i) => (i % 12 + 12) % 12));
+  const hasThird = tones.has(3) || tones.has(4);
+  const isSuspendedTone = !hasThird && (interval === 5 && tones.has(5) || interval === 2 && tones.has(2));
+  const chordRole = chordToneRole(pitch, chord);
+  let role;
+  let lock;
+  if (isSuspendedTone) {
+    role = "third";
+    lock = "quality";
+  } else if (chordRole !== null) {
+    role = chordRole;
+    lock = chordRole === "root" ? "identity" : chordRole === "third" ? "quality" : "voicing";
+  } else {
+    role = "tension";
+    lock = "voicing";
+  }
+  return { role, lock, belongsToChordId: chordId };
+}
+
+export {
+  roleOf
+};
+//# sourceMappingURL=chunk-2ZWMSJH6.js.map

package/dist/chunk-2ZWMSJH6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theory/harmony/index.ts"],"sourcesContent":["import { type Chord, chordToneRole } from '../chord/index.js';\n\n/**\n * Harmonic role a pitch plays within a chord.\n *\n * @category Functional Harmony\n */\nexport type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension' | 'doubling';\n\n/**\n * How firmly a pitch is locked to the chord's identity.\n *\n * - `identity`: moving it produces a different chord (the root).\n * - `quality`: moving it flips the chord quality (the third).\n * - `voicing`: it can move freely without changing chord identity or quality.\n *\n * @category Functional Harmony\n */\nexport type LockLevel = 'identity' | 'quality' | 'voicing';\n\n/**\n * A pitch's role, lock level, and owning chord.\n *\n * @category Functional Harmony\n */\nexport type VoicedRole = {\n  role: HarmonyRole;\n  lock: LockLevel;\n  belongsToChordId: number;\n};\n\n/**\n * Classify a pitch's harmonic role and lock level within a chord.\n *\n * The role comes from the pitch's interval class above the chord root: root (0),\n * third (3/4), fifth (6/7/8), seventh (10/11), and 9/11/13 tensions (2/5/9, and\n * the flat ninth 1). The root locks the chord identity, the third locks its\n * quality, and everything else is free voicing. In a suspended chord (a chord\n * whose intervals include a 4th (5) or 2nd (2) but no third), the suspended tone\n * takes the third's place as the quality-defining tone and is locked to\n * `quality`, since moving it changes the chord. Detecting an octave doubling\n * requires the surrounding voicing, which this single-pitch query does not carry,\n * so `doubling` is part of the type but not returned here.\n *\n * @param pitch MIDI pitch or bare pitch class.\n * @param chord The chord providing the root reference.\n * @param chordId Identifier stored on the result (defaults to 0).\n * @returns The pitch's role, lock level, and owning chord id.\n * @example\n * ```ts\n * import { roleOf, makeChord } from '@libraz/libcantus';\n * roleOf(64, makeChord(0, 'maj')); // E over C major\n * // { role: 'third', lock: 'quality', belongsToChordId: 0 }\n * ```\n * @category Functional Harmony\n */\nexport function roleOf(pitch: number, chord: Chord, chordId = 0): VoicedRole {\n  const interval = (((Math.trunc(pitch) - chord.rootPc) % 12) + 12) % 12;\n  const tones = new Set(chord.intervals.map((i) => ((i % 12) + 12) % 12));\n  const hasThird = tones.has(3) || tones.has(4);\n  const isSuspendedTone =\n    !hasThird && ((interval === 5 && tones.has(5)) || (interval === 2 && tones.has(2)));\n  const chordRole = chordToneRole(pitch, chord);\n  let role: HarmonyRole;\n  let lock: LockLevel;\n  if (isSuspendedTone) {\n    role = 'third'; // suspended tone occupies the third's quality-defining slot\n    lock = 'quality';\n  } else if (chordRole !== null) {\n    role = chordRole;\n    lock = chordRole === 'root' ? 'identity' : chordRole === 'third' ? 'quality' : 'voicing';\n  } else {\n    role = 'tension';\n    lock = 'voicing';\n  }\n  return { role, lock, belongsToChordId: chordId };\n}\n"],"mappings":";;;;;AAwDO,SAAS,OAAO,OAAe,OAAc,UAAU,GAAe;AAC3E,QAAM,aAAc,KAAK,MAAM,KAAK,IAAI,MAAM,UAAU,KAAM,MAAM;AACpE,QAAM,QAAQ,IAAI,IAAI,MAAM,UAAU,IAAI,CAAC,OAAQ,IAAI,KAAM,MAAM,EAAE,CAAC;AACtE,QAAM,WAAW,MAAM,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC;AAC5C,QAAM,kBACJ,CAAC,aAAc,aAAa,KAAK,MAAM,IAAI,CAAC,KAAO,aAAa,KAAK,MAAM,IAAI,CAAC;AAClF,QAAM,YAAY,cAAc,OAAO,KAAK;AAC5C,MAAI;AACJ,MAAI;AACJ,MAAI,iBAAiB;AACnB,WAAO;AACP,WAAO;AAAA,EACT,WAAW,cAAc,MAAM;AAC7B,WAAO;AACP,WAAO,cAAc,SAAS,aAAa,cAAc,UAAU,YAAY;AAAA,EACjF,OAAO;AACL,WAAO;AACP,WAAO;AAAA,EACT;AACA,SAAO,EAAE,MAAM,MAAM,kBAAkB,QAAQ;AACjD;","names":[]}