@libraz/libcantus 0.9.5 → 1.0.0

package/dist/function-DTCt675z.d.ts

@@ -1,299 +0,0 @@
-import { K as KeyScale } from './types-BN6_Q9Kl.js';
-import { C as Chord } from './index-COw1Ky9g.js';
-
-/**
- * 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.
- */
-
-/**
- * The origin of a recognized non-diatonic chord, or null when none applies.
- *
- * @category Functional Harmony
- */
-type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
-/**
- * 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 altered minor forms (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
- */
-declare function isBorrowedChord(chord: Chord, key: KeyScale): boolean;
-/**
- * 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 and altered-minor chords,
- * 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
- */
-declare function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource;
-
-/**
- * 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.
- */
-
-/**
- * A recognized cadence type, or null when a chord pair forms none.
- *
- * @category Functional Harmony
- */
-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
- */
-declare function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence;
-
-/**
- * Roman-numeral parsing and formatting.
- *
- * The {@link ROMAN_STYLE} table is the single source of truth for both
- * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
- * inverses by construction.
- */
-
-/**
- * Build the chord denoted by a Roman numeral in a key.
- *
- * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
- * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
- * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
- * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
- * whose root becomes a local major tonic for the applied chord. Inverted chords
- * carry a `bassPc`.
- *
- * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
- * `m7b5`), since no half-diminished triad exists. Extension and added-tone
- * suffixes are the canonical case-sensitive forms emitted by
- * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
- * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
- * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
- * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
- * A figure string that is neither a recognized inversion nor a supported
- * quality suffix throws rather than silently degrading to a triad.
- *
- * @param text The Roman numeral.
- * @param key The prevailing key.
- * @returns The chord.
- * @example
- * ```ts
- * import { romanToChord, majorKey } from '@libraz/libcantus';
- * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
- * ```
- * @category Functional Harmony
- */
-declare function romanToChord(text: string, key: KeyScale): Chord;
-/**
- * Options for {@link chordToRoman}.
- *
- * @category Functional Harmony
- */
-type ChordToRomanOptions = {
-    /**
-     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
-     * instead of naming its root against the home key (`II7`, `#ivo7`).
-     *
-     * 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 makes {@link chordToRoman} the exact inverse
-     * of {@link romanToChord} for the chords {@link secondaryDominant} builds.
-     */
-    applied?: boolean;
-};
-/**
- * Render a chord as a Roman numeral relative to a key.
- *
- * Diatonic roots take their scale-degree numeral directly, so numerals are
- * correct in both major and minor keys (and any custom scale). The quality
- * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
- * convention. A key that is not heptatonic has no numeral of its own for every
- * degree, so its roots are named against its parallel major.
- *
- * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
- * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
- * chords; added-tone and extended qualities have no lossless figure and render
- * in root position instead (the bass is dropped, pitch classes are preserved).
- *
- * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
- * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
- * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
- * is no unambiguous way to write such a bass; a caller that must keep it should
- * read `chord.bassPc` alongside the numeral.
- *
- * @param chord The chord to name.
- * @param key The prevailing key.
- * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals.
- * @returns The Roman numeral string.
- * @example
- * ```ts
- * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
- * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
- * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
- * ```
- * @category Functional Harmony
- */
-declare function chordToRoman(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): string;
-
-/**
- * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
- * mirroring, and full chord analysis.
- *
- * 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.
- */
-
-/**
- * The three broad harmonic functions of tonal music.
- *
- * @category Functional Harmony
- */
-type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
-/**
- * Whether a key's scale has a minor third and no major third (a minor key).
- *
- * @category Functional Harmony
- */
-declare function isMinorKey(key: KeyScale): boolean;
-/**
- * The harmonic function of a chord in a key.
- *
- * The root's offset above the tonic gives the baseline mapping, which follows
- * common-practice major-key function and is a useful approximation in minor and
- * for borrowed chords. Chord quality then refines it where the sonority settles
- * 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.
- * - The Neapolitan is subdominant.
- * - A major triad on bVI or bVII of a major key is subdominant — the borrowed
- *   pop cadence chord, distinct from the bVII7 above, which has a seventh and
- *   is a dominant sonority.
- *
- * @param chord The chord.
- * @param key The prevailing key.
- * @returns The harmonic function.
- * @example
- * ```ts
- * import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
- * functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
- * functionOf(makeChord(10, 'maj'), majorKey(0)); // 'subdominant' — borrowed bVII
- * ```
- * @category Functional Harmony
- */
-declare function functionOf(chord: Chord, key: KeyScale): HarmonicFunction;
-/**
- * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
- *
- * @category Functional Harmony
- */
-type ChordAnalysis = {
-    function: HarmonicFunction;
-    borrowed: boolean;
-    source: BorrowedSource;
-    roman: string;
-};
-/**
- * Whether every pitch class of a chord belongs to the key's scale.
- *
- * The test is strict against the key's own mode mask: in a natural-minor key
- * the harmonic-minor dominant (major V) is *not* diatonic, since the raised
- * leading tone lies outside the mask. Borrowing predicates treat that case as
- * an in-key alteration separately (see {@link isBorrowedChord}).
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if all chord pitch classes are scale tones.
- * @category Functional Harmony
- */
-declare function isDiatonic(chord: Chord, key: KeyScale): boolean;
-/**
- * The parallel key: same tonic, opposite mode.
- *
- * A key with a minor third (natural/harmonic/melodic minor, dorian, phrygian)
- * maps to the parallel major; any other key maps to the parallel natural minor.
- *
- * @param key The key to mirror.
- * @returns The parallel major or natural-minor key on the same tonic.
- * @category Functional Harmony
- */
-declare function parallelKey(key: KeyScale): KeyScale;
-/**
- * Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.
- *
- * The function is quality-aware (see the predicates behind it), the source
- * follows {@link borrowedSource}, and the numeral comes from
- * {@link chordToRoman}. `borrowed` is true whenever a source is identified —
- * including the Neapolitan, which the stricter parallel-mode predicate
- * {@link isBorrowedChord} does not count.
- *
- * @param chord The chord to analyze.
- * @param key The prevailing key.
- * @param opts Options used when rendering the Roman numeral.
- * @returns The chord analysis.
- * @example
- * ```ts
- * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
- * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
- * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }
- * ```
- * @category Functional Harmony
- */
-declare function analyzeChord(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): ChordAnalysis;
-/**
- * The secondary dominant (V7) that tonicizes a scale degree.
- *
- * @param targetDegree 0-based scale degree to tonicize.
- * @param key The prevailing key.
- * @returns A dominant-seventh chord a fifth above the target's root.
- * @throws If `targetDegree` is not an integer naming a degree in `key`.
- * @category Functional Harmony
- */
-declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;
-
-export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, type ChordToRomanOptions as b, analyzeChord as c, borrowedSource as d, chordToRoman as e, detectCadence as f, functionOf as g, isDiatonic as h, isBorrowedChord as i, isMinorKey as j, parallelKey as p, romanToChord as r, secondaryDominant as s };

package/dist/index-B2Ulxxpo.d.cts

@@ -1,144 +0,0 @@
-import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
-import { C as Chord } from './index-oTQbYYIs.cjs';
-
-/**
- * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
- *
- * @category Arrangement & Analysis
- */
-type SafetyProfile = 'strict' | 'pop';
-/**
- * Overall placeability verdict for a candidate pitch.
- *
- * @category Arrangement & Analysis
- */
-declare enum NoteSafety {
-    Safe = 0,
-    Warning = 1,
-    Dissonant = 2
-}
-/**
- * Bit flags describing why a pitch received its verdict.
- *
- * @category Arrangement & Analysis
- */
-declare enum ReasonFlag {
-    ChordTone = 1,
-    Tension = 2,
-    AvoidNote = 4,
-    ScaleTone = 8,
-    NonScale = 16,
-    OutOfRange = 32,
-    Tritone = 64,
-    LargeLeap = 128,
-    MinorSecond = 256,
-    MajorSeventh = 512,
-    VerticalDissonance = 1024,
-    ParallelPerfect = 2048,
-    HiddenParallel = 4096,
-    VoiceCrossing = 8192,
-    Suspension = 16384,
-    NeedsResolution = 32768,
-    MelodicTritone = 65536
-}
-/**
- * A neighbouring voice's current and previous pitch.
- *
- * @category Arrangement & Analysis
- */
-type VoiceSnapshot = {
-    pitch: number;
-    prevPitch?: number;
-};
-/**
- * Everything needed to evaluate one candidate pitch.
- *
- * @category Arrangement & Analysis
- */
-type SafetyQuery = {
-    profile: SafetyProfile;
-    candidatePitch: number;
-    prevPitch?: number;
-    chord: Chord | null;
-    key: KeyScale;
-    otherVoices: VoiceSnapshot[];
-    strongBeat: boolean;
-    vocalLow?: number;
-    vocalHigh?: number;
-};
-/**
- * The verdict, reason flags, and optional resolution guidance.
- *
- * @category Arrangement & Analysis
- */
-type SafetyResult = {
-    safety: NoteSafety;
-    reasons: number;
-    resolveTo?: number;
-    suggestions?: number[];
-    rationale?: string;
-};
-/**
- * Evaluate the safety of placing a candidate pitch in a voice.
- *
- * Reasons are merged from harmonic context (chord tone / tension / avoid / scale)
- * and counterpoint (vertical dissonance, parallels, voice crossing). The `strict`
- * profile treats avoid notes and parallels as dissonant; `pop` treats them as
- * warnings. The final verdict is the worst severity among the reasons.
- *
- * @param q The candidate and its harmonic/voice-leading context.
- * @returns The verdict, reason bitmask, and optional resolution guidance.
- * @example
- * ```ts
- * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';
- * const result = evaluateSafety({
- *   profile: 'pop',
- *   candidatePitch: 60, // C over a C major chord
- *   chord: makeChord(0, 'maj'),
- *   key: majorKey(0),
- *   otherVoices: [],
- *   strongBeat: true,
- * });
- * result.safety === NoteSafety.Safe; // true — C is a chord tone
- * ```
- * @category Arrangement & Analysis
- */
-declare function evaluateSafety(q: SafetyQuery, opts?: EvaluateSafetyOptions): SafetyResult;
-/**
- * Options for {@link evaluateSafety}.
- *
- * @category Arrangement & Analysis
- */
-type EvaluateSafetyOptions = {
-    /**
-     * Whether to search for safe replacement pitches when the verdict is not
-     * safe. Turning it off skips up to two dozen extra evaluations per rejected
-     * pitch, which is worth doing when only the verdict is wanted.
-     *
-     * @defaultValue true
-     */
-    suggestions?: boolean;
-};
-/**
- * Enumerate placeable pitches in a range, chord tones first, descending.
- *
- * @param q The safety context minus the candidate pitch.
- * @param pitchLow Lowest MIDI pitch to consider (inclusive).
- * @param pitchHigh Highest MIDI pitch to consider (inclusive).
- * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
- * @throws If either bound is non-finite/non-integral, reversed, or exceeds the generation budget.
- * @example
- * ```ts
- * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
- * const pitches = enumerateSafePitches(
- *   { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },
- *   60,
- *   72,
- * );
- * pitches; // placeable pitches in [60, 72], chord tones first, each group descending
- * ```
- * @category Arrangement & Analysis
- */
-declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
-
-export { type EvaluateSafetyOptions as E, NoteSafety as N, ReasonFlag as R, type SafetyProfile as S, type VoiceSnapshot as V, type SafetyQuery as a, type SafetyResult as b, evaluateSafety as c, enumerateSafePitches as e };

package/dist/index-BkYJ0xMq.d.cts

@@ -1,152 +0,0 @@
-import { T as TimeSignature } from './index-DXd9JikN.cjs';
-import { K as KeyScale, N as NoteEvent } from './types-BN6_Q9Kl.cjs';
-import { C as Chord, b as ChordSegment, c as ChordSpan } from './index-oTQbYYIs.cjs';
-import { C as Cadence } from './function-CxixTB02.cjs';
-
-/**
- * A beat-indexed sequence of chord segments.
- *
- * @category Arrangement & Analysis
- */
-type ChordTimeline = {
-    /** The chord sounding at a beat, or null when no segment covers it. */
-    at: (beat: number) => Chord | null;
-    segments: ChordSegment[];
-};
-/**
- * Build a chord timeline from placed chords.
- *
- * Each chord spans from its `startBeat` to the next chord's `startBeat`; the last
- * chord runs to `totalBeats`. Segments with no positive length (from duplicate
- * onsets or a last chord at or past `totalBeats`) are dropped. `at(beat)` returns
- * the covering segment's chord, or null when the beat lies outside every segment.
- *
- * @param chords Placed chords in time order.
- * @param totalBeats End of the timeline in beats.
- * @returns A queryable chord timeline.
- * @category Arrangement & Analysis
- */
-declare function chordTimelineFromChords(chords: readonly ChordSpan[], totalBeats: number): ChordTimeline;
-/**
- * Options controlling {@link chordTimelineFromNotes}.
- *
- * @category Arrangement & Analysis
- */
-type ChordTimelineOptions = {
-    /** Key context; inferred from the notes with {@link detectKeyFromNotes} when omitted. */
-    key?: KeyScale;
-    /**
-     * Time signature used for metric accents; defaults to 4/4.
-     *
-     * @defaultValue `4/4`
-     */
-    ts?: TimeSignature;
-    /**
-     * Window length in beats per chord slot; defaults to one bar of `ts`.
-     *
-     * @defaultValue one bar of `ts`
-     */
-    harmonicRhythm?: number;
-    /**
-     * End of the analyzed span in beats; defaults to the end of the last note.
-     *
-     * @defaultValue the end of the last note
-     */
-    totalBeats?: number;
-    /**
-     * Upper bound on the work this call may do — note counts, windows, and
-     * candidate counts are each checked against it before anything is allocated.
-     *
-     * Raise it to analyse a piece larger than the default allows; the default is
-     * {@link DEFAULT_GENERATION_BUDGET}, chosen so a runaway input fails fast
-     * rather than blocking the thread.
-     *
-     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
-     */
-    budget?: number;
-};
-/**
- * The result of {@link chordTimelineFromNotes}.
- *
- * @category Arrangement & Analysis
- */
-type ChordTimelineResult = {
-    /** The inferred timeline, with adjacent identical chords merged. */
-    timeline: ChordTimeline;
-    /** The key used for the analysis (given or inferred). */
-    key: KeyScale;
-    /** One confidence value in [0, 1] per segment, in segment order. */
-    segmentConfidence: number[];
-};
-/**
- * Infer a chord timeline from raw multi-track notes.
- *
- * The span `[0, totalBeats)` is sliced into `harmonicRhythm`-beat windows; each
- * window's chord is inferred from a pitch-class weight histogram of the notes
- * overlapping it (weight = overlap duration x velocity x metric-accent bonus
- * for onsets in the window). Adjacent windows carrying the identical chord are
- * merged into one segment; windows with no notes produce no segment, so
- * `at(beat)` returns null there. Each segment carries a confidence in [0, 1]:
- * the fraction of the window weight explained by chord tones, reduced when the
- * match is inexact, and duration-weighted across merged windows.
- *
- * Notes with a zero or negative duration never sound, so they are dropped at
- * ingest: they contribute to neither the key inference, the span, nor any
- * window's histogram.
- *
- * @param notes The notes to analyze (any number of tracks, flattened).
- * @param opts Analysis options; see {@link ChordTimelineOptions}.
- * @returns The inferred timeline, the key used, and per-segment confidences.
- * @throws If `harmonicRhythm` is not positive.
- * @example
- * ```ts
- * import { chordTimelineFromNotes } from '@libraz/libcantus';
- * const notes = [
- *   { pitch: 60, startBeat: 0, durationBeat: 2 }, // C
- *   { pitch: 64, startBeat: 0, durationBeat: 2 }, // E
- *   { pitch: 67, startBeat: 0, durationBeat: 2 }, // G
- * ];
- * const { timeline, key } = chordTimelineFromNotes(notes);
- * timeline.at(0); // the chord inferred over beat 0, or null
- * ```
- * @category Arrangement & Analysis
- */
-declare function chordTimelineFromNotes(notes: NoteEvent[], opts?: ChordTimelineOptions): ChordTimelineResult;
-/**
- * A cadence found between two consecutive timeline segments.
- *
- * @category Arrangement & Analysis
- */
-type CadenceHit = {
-    /** The beat where the cadence arrives (the second chord's onset). */
-    atBeat: number;
-    type: Exclude<Cadence, null>;
-    from: Chord;
-    to: Chord;
-};
-/**
- * Find cadences between consecutive segments of a chord timeline.
- *
- * Each temporally adjacent segment pair is classified with
- * {@link detectCadence}; pairs forming no cadence are skipped. Segments
- * separated by a gap (a rest in the timeline) are not a chord-to-chord
- * progression, so they are never paired.
- *
- * @param timeline The chord timeline to scan.
- * @param key The prevailing key.
- * @returns The cadences found, in time order.
- * @example
- * ```ts
- * import { chordTimelineFromNotes, detectCadences } from '@libraz/libcantus';
- * const notes = [
- *   { pitch: 67, startBeat: 0, durationBeat: 4 }, // G, a dominant
- *   { pitch: 60, startBeat: 4, durationBeat: 4 }, // C, the tonic
- * ];
- * const { timeline, key } = chordTimelineFromNotes(notes);
- * const cadences = detectCadences(timeline, key);
- * ```
- * @category Arrangement & Analysis
- */
-declare function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceHit[];
-
-export { type CadenceHit as C, type ChordTimeline as a, type ChordTimelineOptions as b, type ChordTimelineResult as c, chordTimelineFromChords as d, chordTimelineFromNotes as e, detectCadences as f };