@libraz/libcantus 1.0.0 → 1.1.0

package/dist/{index-Chbst3Jx.d.ts → index-BpWOhkkE.d.ts}

@@ -1,6 +1,6 @@
-import { c as ChordLike, K as KeyLike, j as ChordToneRole, b as Chord, k as KeyRelation, e as ChordSegment, V as VoiceSnapshot, g as ChordSpan } from './index-szBv3496.js';
-import { T as TimeSignature, c as MeterMap } from './index-Cj49F892.js';
-import { d as KeyScale, g as NoteEvent } from './index-B9MNZboQ.js';
+import { c as ChordLike, K as KeyLike, i as ChordToneRole, q as SpelledKeyLike, b as Chord, n as ResolvedKey, j as KeyRelation, e as ChordSegment, V as VoiceSnapshot, g as ChordSpan } from './coerce-wwdELNYS.js';
+import { b as MeterLike } from './index-Ci3xyows.js';
+import { h as NoteEvent, e as KeyScale } from './index-Cy15oTvh.js';
 
 /**
  * The vocabulary the analyze layer explains itself in.
@@ -222,33 +222,41 @@ type DetectCadenceOptions = {
  * 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
+ * - plagal: IV, the chord on the key's own fourth degree, to I
  * - modal: bVII to I, the cadence of rock and modal writing
  * - deceptive: V to the key's own submediant, plus the borrowed bVI of a major
  *   key
  * - phrygian: iv6 to V of a minor key, the half cadence whose bass falls a
  *   semitone from b6 to 5
- * - half: any other chord than the dominant itself to V
- *
- * Both are read as scale degrees rather than as semitone distances, so a mode
- * cadences onto the submediant and the dominant it actually has: the deceptive
- * arrival of dorian is a major sixth above the tonic and that of phrygian a
- * minor sixth. A half cadence normally rests on the major third that carries
- * the leading tone, but where the key's own dominant has no leading tone —
- * aeolian and dorian, the modal `v` of pop writing — the arrival's own third
- * suffices as long as the key contains it. That relaxation never applies to a
- * key whose dominant does carry the leading tone, so a borrowed minor `v` in a
- * major key is no half cadence.
+ * - half: any other chord than the dominant itself to V, the cadential six-four
+ *   standing on the dominant's own bass included
+ *
+ * These are read as scale degrees rather than as semitone distances, so a mode
+ * cadences from and onto the degrees it actually has: the deceptive arrival of
+ * dorian is a major sixth above the tonic and that of phrygian a minor sixth,
+ * and the subdominant a plagal cadence falls from is the tritone above the
+ * tonic in lydian. The two borrowed types are the exception, and are stated as
+ * the fixed offsets they name: `modal` is the flattened seventh whatever the
+ * key writes on that degree, and the Phrygian bass falls from the lowered
+ * submediant. A half cadence normally rests on the major third that carries
+ * the leading tone, but where the key's own dominant has no leading tone — the
+ * modal `v` of dorian, mixolydian and the pop writing built on them — the
+ * arrival's own third suffices as long as the key contains it. That relaxation
+ * belongs to the modes alone: a borrowed minor `v` in a major key is no half
+ * cadence, and neither is the `v` of a minor key, which cadences through the
+ * raised seventh it writes as an accidental rather than in its scale.
  *
  * A static V-to-V repeat with no root motion is not a cadence and yields a null
- * type, and so is the tonic six-four resolving onto the dominant it already
- * stands on: that pair is one harmony moving inside itself. Passing that
- * six-four as `approach` when the dominant is the `from` chord is what lets the
- * cadence be reported as the single event it is — the type and the beat are
- * still the dominant's resolution, while the `rationale` says the cadence began
- * at the six-four. A six-four the bass leaves instead (`IV-I64-IV`, or a
- * neighbouring one over the tonic) is an ordinary inverted tonic and is read as
- * one.
+ * type. The tonic six-four resolving onto the dominant it stands on is a half
+ * cadence, and the most ordinary one there is: `I - I64 - V` closes the
+ * antecedent of a period, and the six-four is a double appoggiatura over the
+ * dominant's own bass rather than a chord that keeps the motion going. Where
+ * that dominant goes on to resolve, the pair and the resolution are one event —
+ * passing the six-four as `approach` when the dominant is the `from` chord is
+ * what lets it be reported as one, with the type and the beat still the
+ * dominant's resolution while the `rationale` says the cadence began at the
+ * six-four. A six-four the bass leaves instead (`IV-I64-IV`, or a neighbouring
+ * one over the tonic) is an ordinary inverted tonic and is read as one.
  *
  * An authentic cadence is graded perfect or imperfect. Perfect takes the
  * dominant to the tonic with both chords in root position and the tonic in the
@@ -336,7 +344,7 @@ declare function detectCadence(from: ChordLike, to: ChordLike, key: KeyLike, opt
  * ```
  * @category Functional Harmony
  */
-declare function romanToChord(text: string, key: KeyLike): Chord;
+declare function romanToChord(text: string, key: SpelledKeyLike): Chord;
 /**
  * Options for {@link chordToRoman}.
  *
@@ -350,10 +358,17 @@ type ChordToRomanOptions = {
      * Off by default: naming the root is always a correct spelling, whereas
      * whether a chromatic dominant is genuinely applied is a reading only the
      * caller can make. Turning it on names the chords {@link secondaryDominant}
-     * builds as the applied numerals they are, except where the target degree
-     * carries no perfect fifth: nothing tonicizes a diminished triad, so a chord
-     * over the seventh degree of a major key stays `#IV7` rather than becoming a
-     * numeral no harmony text writes.
+     * builds as the applied numerals they are, except in three cases, where the
+     * numeral names the root against the home key as it does with this off:
+     *
+     * - The target degree carries no perfect fifth: nothing tonicizes a
+     *   diminished triad, so a chord over the seventh degree of a major key stays
+     *   `#IV7` rather than becoming a numeral no harmony text writes.
+     * - The target is the tonic, which its own dominant points at: `V7` is the
+     *   key's dominant and `V/I` is a numeral no harmony text writes either.
+     * - The chord is diatonic to the key, which keeps the function of its degree
+     *   rather than tonicizing another. `G7` is `VII7` in A minor and `I7` in C
+     *   mixolydian, not `V7/III` and `V7/IV`.
      */
     applied?: boolean;
     /**
@@ -392,6 +407,11 @@ type ChordToRomanOptions = {
  * A chord sounding one of the augmented sixths over an explicit bass on the
  * lowered submediant renders as `It6`, `Fr6` or `Ger6`, since no numeral names
  * those chords; see {@link augmentedSixthKind} for exactly when that applies.
+ * That reading is made against the key as written, because what separates an
+ * augmented sixth from the seventh chord it sounds like is its letters: the
+ * German sixth of Ab minor is named from the Fb Ab Cb D it is written with, not
+ * from the letters those pitch classes take once the key has been respelled as
+ * a G# minor.
  *
  * @param chord The chord to name, as a chord symbol, chord data, or a `Chord`.
  * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
@@ -502,11 +522,14 @@ declare function isMinorKey(key: KeyLike): boolean;
  * an ambiguity the root offset cannot:
  *
  * - A chord that *sounds* like a dominant — a major third with a minor seventh,
- *   or a diminished-family chord — and is not diatonic to the key has dominant
- *   function when its root resolves down a fifth or by a semitone onto a
- *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
- *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
- *   than inheriting the function of the degree they happen to sit on.
+ *   or a diminished-family chord — and is neither diatonic to the key nor
+ *   borrowed from its parallel mode has dominant function when its root
+ *   resolves onto a degree that can be made a local tonic. This is what makes an
+ *   applied dominant (`A7` in C, which tonicizes ii) and its tritone substitute
+ *   (`Db7`) read as dominant rather than inheriting the function of the degree
+ *   they happen to sit on. A bare major triad carries no tritone, so it only
+ *   tonicizes by falling a fifth onto a degree other than the tonic: the Picardy
+ *   third of a minor key and its borrowed major IV sound their own degrees.
  * - The Neapolitan is subdominant.
  * - An augmented sixth is subdominant. All three are altered predominants that
  *   resolve outward onto the dominant, so they take subdominant function even
@@ -646,8 +669,8 @@ declare function secondaryDominant(targetDegree: number, key: KeyLike): Chord;
  * @example
  * ```ts
  * import { makeChord, secondaryDominantOf } from '@libraz/libcantus';
- * secondaryDominantOf(makeChord(8, 'maj'));
- * // { rootPc: 3, quality: 'dom7' } — Eb7 tonicizes the borrowed bVI of C major
+ * secondaryDominantOf(makeChord(8, 'maj')).rootPc; // 3 — Eb7 tonicizes the
+ * // borrowed bVI of C major
  * ```
  * @category Functional Harmony
  */
@@ -727,8 +750,20 @@ type KeyRegion = {
     startBeat: number;
     /** End of the region, exclusive. */
     endBeat: number;
-    /** The key in force across the region. */
-    key: KeyScale;
+    /**
+     * The key in force across the region, owned by it: every entry point hands
+     * back a key of the region's own, so writing to one changes neither the other
+     * regions of the same run nor what a later call reports.
+     *
+     * Whole, whichever way the region was built. A caller who named the key hands
+     * its spelling and scale form down, and a key the analysis found is spelled
+     * and formed the way {@link resolveKey} reads a bare scale — the reading every
+     * other layer would have made of it. There is no third state to guess at: a
+     * key/scale alone says nothing about how it is written, so a region carrying
+     * one would report whichever spelling those pitch classes read best from, and
+     * an Ab minor handed in would come back out a G# minor.
+     */
+    key: ResolvedKey;
     /**
      * How well the region's music fits the key, in [0, 1]: the correlation
      * between the span's pitch-class distribution and the key's profile, with
@@ -770,7 +805,7 @@ type KeyTimelineOptions = {
      *
      * @defaultValue `4/4`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * The meter as it changes over the span. Bar lines, downbeats and the metric
      * accents the search discounts a modulation by all follow the signature in
@@ -779,7 +814,7 @@ type KeyTimelineOptions = {
      *
      * @defaultValue 4/4 throughout
      */
-    meters?: MeterMap;
+    meters?: MeterLike;
     /**
      * Expected length of one key area in beats; defaults to four bars of the
      * opening meter.
@@ -881,6 +916,12 @@ declare function keyTimelineFromNotes(notes: readonly NoteEvent[], opts?: KeyTim
  * confidence, as it does in the note path, but takes no part in choosing which
  * keys are reported: that is settled by how the chords read.
  *
+ * A region's evidence is the run of segments it was grouped from, which is the
+ * same reading the search itself makes of them. Where the segments given
+ * overlap each other — a chart is a sequence, so a chord timeline's are not —
+ * a chord held past the segment after it argues for its own segment's key
+ * rather than for both.
+ *
  * @param chords The chord segments to analyze, in time order; pass a chord
  *   timeline's `segments`.
  * @param opts Analysis options; see {@link KeyTimelineOptions}.
@@ -916,7 +957,7 @@ declare function detectModulations(chords: readonly ChordSegment[], opts?: KeyTi
  * ```
  * @category Arrangement & Analysis
  */
-declare function prevailingKeyOf(regions: readonly KeyRegion[]): KeyScale | null;
+declare function prevailingKeyOf(regions: readonly KeyRegion[]): ResolvedKey | null;
 
 /**
  * A suspension figure, named by the interval above the bass and the interval it
@@ -1033,7 +1074,7 @@ type IdentifiedVoiceNote = VoiceNote & {
  * ```
  * @category Arrangement & Analysis
  */
-type KeyContext = KeyScale | ((beat: number) => KeyScale);
+type KeyContext = KeyLike | ((beat: number) => KeyScale);
 /**
  * Give plain note events the ids {@link analyzeVoice} reports back.
  *
@@ -1055,8 +1096,10 @@ declare function toVoiceNotes(events: readonly NoteEvent[]): IdentifiedVoiceNote
  * resolving by step the other way), and escape tones, then fall back to
  * tension, avoid, or an unresolved-dissonance label. The figures are named as
  * {@link classifyMelodyTones} names them, so a caller reading a melody through
- * both layers gets one vocabulary; that classifier weighs the metre as well,
- * which this one is not given, so it is the stricter of the two. Leading-tone resolutions are noted
+ * both layers gets one vocabulary. The two answer different questions and
+ * neither refines the other: that classifier weighs the metre, which this one is
+ * not given, so it can call ornamental a note this one reads as a chord tone,
+ * and the reverse. Leading-tone resolutions are noted
  * additionally, judged against the key in force at the beat the resolution
  * lands on, so a modulation is heard from its new tonic.
  *
@@ -1103,6 +1146,32 @@ type ChordTimeline = {
     at: (beat: number) => Chord | null;
     segments: ChordSegment[];
 };
+/**
+ * Reject a value that is not a chord timeline.
+ *
+ * A timeline is the one argument a host is most likely to hold from somewhere
+ * else — an in-memory project value, a previous run restored to a timeline, or
+ * another library's output — and
+ * it is read field by field deep inside an analysis. Checking it once at the
+ * entrance names the argument that is wrong instead of reporting the library's
+ * own `TypeError` from wherever the first `segments` lookup happened to be.
+ *
+ * The segments are checked too: every reader of a timeline compares beats, and
+ * a segment whose bounds are missing compares as neither before nor after, so
+ * it disappears from the analysis rather than being reported.
+ *
+ * @param timeline The timeline as the caller passed it.
+ * @param name What the argument is called in an error message.
+ * @returns The same timeline.
+ * @throws If the value is not a timeline of chord segments.
+ * @example
+ * ```ts
+ * import { assertChordTimeline, chordTimelineFromChords } from '@libraz/libcantus';
+ * assertChordTimeline(chordTimelineFromChords([], 4)); // the timeline, unchanged
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function assertChordTimeline(timeline: ChordTimeline, name?: string): ChordTimeline;
 /**
  * Build a chord timeline from placed chords.
  *
@@ -1139,15 +1208,19 @@ type ChordTimelineOptions = {
      * Key context held across the whole span. Omit it to have the key searched
      * for over time with {@link keyTimelineFromNotes}, which is what lets a piece
      * that modulates be analysed against the key actually in force.
+     *
+     * Taken in whatever form the caller holds a key, and kept whole: the region
+     * built from it carries the spelling and the scale form it was named with, so
+     * an Ab minor stated here is an Ab minor in the result.
      */
-    key?: KeyScale;
+    key?: KeyLike;
     /**
      * A single time signature held across the whole span, as sugar for a
      * one-element `meters`; defaults to 4/4. Giving both is an input error.
      *
      * @defaultValue `4/4`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * The meter as it changes over the span. Bar lines, downbeats and metric
      * weight all follow the signature in force at the beat in question, so a
@@ -1155,7 +1228,7 @@ type ChordTimelineOptions = {
      *
      * @defaultValue 4/4 throughout
      */
-    meters?: MeterMap;
+    meters?: MeterLike;
     /**
      * Length of the pickup in beats, when the piece starts with one.
      *
@@ -1184,18 +1257,21 @@ type ChordTimelineOptions = {
      */
     harmonicRhythm?: number;
     /**
-     * Shortest chord the `'dynamic'` search may report, in beats; defaults to one
-     * beat. Lower it to catch changes on off-beats, at the cost of proportionally
-     * more work. Values above `harmonicRhythm` are clamped to it, and the option
-     * is ignored under `'grid'` segmentation.
+     * Resolution the `'dynamic'` search looks for changes at, in beats; defaults
+     * to one main pulse of the meter — a quarter in 4/4, a dotted quarter in 6/8.
+     * Lower it to catch changes on off-beats, at the cost of proportionally more
+     * work. Values above `harmonicRhythm` are clamped to it, and the option is
+     * ignored under `'grid'` segmentation.
      *
      * The search reads it as a resolution rather than as an exact slot length: it
-     * rounds down to a whole division of `harmonicRhythm`, so `0.6` against a
-     * four-beat chord is read in sevenths of it. That keeps the beats one
-     * expected chord gives way to the next on the grid whatever resolution is
-     * asked for, and with them every change a coarser setting found.
+     * rounds down to a whole division of the meter's pulse, so `0.6` in 4/4 is
+     * read in half-beats. That keeps every pulse of the meter, and the bar lines
+     * with them, on the grid whatever resolution is asked for, and with them every
+     * change a coarser setting found. A resolution coarser than one pulse is
+     * therefore read as one pulse rather than stepping over the beats a change is
+     * heard on.
      *
-     * @defaultValue `1`
+     * @defaultValue one main pulse of the meter
      */
     minChordBeats?: number;
     /**
@@ -1237,7 +1313,7 @@ type ChordTimelineResult = {
      * The key held longest across {@link ChordTimelineResult.keys} — the one to
      * print on a key signature or hand to a generator that takes a single key.
      */
-    prevailingKey: KeyScale;
+    prevailingKey: ResolvedKey;
     /** One confidence value in [0, 1] per segment, in segment order. */
     segmentConfidence: number[];
 };
@@ -1245,7 +1321,8 @@ type ChordTimelineResult = {
  * Infer a chord timeline from raw multi-track notes.
  *
  * Chord boundaries are searched for rather than assumed: the span is examined
- * in `minChordBeats` slots, and the change points that best explain the notes
+ * in slots of one main pulse, subdivided as finely as `minChordBeats` asks for,
+ * and the change points that best explain the notes
  * are chosen, trading each slot's harmonic fit against a cost per chord change
  * that a strong beat discounts. A bar holding two chords therefore yields two
  * segments and a bar holding one yields one, without the caller having to know
@@ -1340,4 +1417,4 @@ type CadenceHit = {
  */
 declare function detectCadences(timeline: ChordTimeline, key: KeyContext): CadenceHit[];
 
-export { type AnalyzeChordOptions as A, type BorrowedSource as B, type CadenceHit as C, type DetectCadenceOptions as D, type ExplainRomanOptions as E, isMinorKey as F, keyTimelineFromNotes as G, type HarmonicFunction as H, type IdentifiedVoiceNote as I, pivotChords as J, type KeyContext as K, prevailingKeyOf as L, romanToChord as M, secondaryDominant as N, secondaryDominantOf as O, type PivotChord as P, toVoiceNotes as Q, type RejectedCandidate as R, type SuspensionFigure as S, type TheoryLabel as T, type VoiceNote as V, type AnalyzedNote as a, type CadenceResult as b, type ChordAnalysis as c, type ChordSegmentation as d, type ChordTimeline as e, type ChordTimelineOptions as f, type ChordTimelineResult as g, type ChordToRomanOptions as h, type KeyProfileName as i, type KeyProfilePair as j, type KeyRegion as k, type KeyTimelineOptions as l, type RomanExplanation as m, analyzeChord as n, analyzeVoice as o, borrowedSource as p, chordTimelineFromChords as q, chordTimelineFromNotes as r, chordToRoman as s, detectCadence as t, detectCadences as u, detectModulations as v, explainRoman as w, functionOf as x, isBorrowedChord as y, isDiatonic as z };
+export { type AnalyzeChordOptions as A, type BorrowedSource as B, type CadenceHit as C, type DetectCadenceOptions as D, type ExplainRomanOptions as E, isDiatonic as F, isMinorKey as G, type HarmonicFunction as H, type IdentifiedVoiceNote as I, keyTimelineFromNotes as J, type KeyContext as K, pivotChords as L, prevailingKeyOf as M, romanToChord as N, secondaryDominant as O, type PivotChord as P, secondaryDominantOf as Q, type RejectedCandidate as R, type SuspensionFigure as S, type TheoryLabel as T, toVoiceNotes as U, type VoiceNote as V, type AnalyzedNote as a, type CadenceResult as b, type ChordAnalysis as c, type ChordSegmentation as d, type ChordTimeline as e, type ChordTimelineOptions as f, type ChordTimelineResult as g, type ChordToRomanOptions as h, type KeyProfileName as i, type KeyProfilePair as j, type KeyRegion as k, type KeyTimelineOptions as l, type RomanExplanation as m, analyzeChord as n, analyzeVoice as o, assertChordTimeline as p, borrowedSource as q, chordTimelineFromChords as r, chordTimelineFromNotes as s, chordToRoman as t, detectCadence as u, detectCadences as v, detectModulations as w, explainRoman as x, functionOf as y, isBorrowedChord as z };