@libraz/libcantus 0.9.0 → 0.9.2

package/dist/theory/index.d.cts

@@ -0,0 +1,535 @@
+import { C as Chord } from '../index-BOBXBNwP.cjs';
+export { a as ChordQuality, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from '../index-BOBXBNwP.cjs';
+import { d as VoicingOptions } from '../styled-BjXtOFNk.cjs';
+export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from '../styled-BjXtOFNk.cjs';
+import { K as KeyScale } from '../types-MGP29r3t.cjs';
+export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-BdeQ1r_p.cjs';
+export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from '../index-DZ1M21do.cjs';
+import { N as Note } from '../index-CGMZNCx6.cjs';
+
+/**
+ * Total voice-leading cost between two voicings: the sum of absolute semitone
+ * motion across voices, plus a moderate {@link HIDDEN_PERFECT_PENALTY} when the
+ * outer-voice (bass–soprano) pair reaches a hidden/direct perfect fifth or
+ * octave by similar motion. The arrays must be the same length; when they
+ * differ the voicings are not comparable and the cost is `Infinity`.
+ *
+ * @param from The previous voicing, one MIDI pitch per voice.
+ * @param to The next voicing, one MIDI pitch per voice.
+ * @returns The summed absolute motion (plus any hidden-perfect penalty), or
+ *   `Infinity` when lengths differ.
+ * @category Voicing & Counterpoint
+ */
+declare function voiceLeadingCost(from: number[], to: number[]): number;
+/**
+ * Voice a single chord to follow smoothly from an arbitrary current voicing.
+ *
+ * Candidate voicings of `chord` are enumerated within ranges taken from `opts`,
+ * or — when neither `voices` nor `ranges` is given — from a one-octave window
+ * around each pitch of `current` (so the result matches `current`'s voice
+ * count). Each candidate is scored by structural quality, voice-leading motion
+ * from `current`, and a large penalty per counterpoint violation; the lowest
+ * scoring candidate is returned, ascending.
+ *
+ * @param current The current voicing to lead from, ascending (index 0 = lowest).
+ * @param chord The next chord to voice.
+ * @param opts Voicing options; when omitted, ranges follow `current`'s span.
+ * @returns The chosen voicing, ascending with one MIDI pitch per voice.
+ * @throws If no voicing fits the derived ranges.
+ * @category Voicing & Counterpoint
+ */
+declare function nextVoicing(current: number[], chord: Chord, opts?: VoicingOptions): number[];
+
+/**
+ * Whether an upper voice has crossed below a lower voice.
+ *
+ * @param upperPitch Pitch of the nominally higher voice.
+ * @param lowerPitch Pitch of the nominally lower voice.
+ * @returns True when the upper voice sits below the lower voice.
+ * @category Voicing & Counterpoint
+ */
+declare function createsVoiceCrossing(upperPitch: number, lowerPitch: number): boolean;
+/**
+ * Whether two simultaneous pitches form a dissonance.
+ *
+ * @param a First pitch.
+ * @param b Second pitch.
+ * @param twoVoice When true, the perfect fourth counts as dissonant.
+ * @returns True when the vertical interval is dissonant.
+ * @category Voicing & Counterpoint
+ */
+declare function createsVerticalDissonance(a: number, b: number, twoVoice: boolean): boolean;
+/**
+ * Whether a melodic move is a forbidden leap: a tritone, either seventh (minor
+ * or major), or any leap wider than an octave.
+ *
+ * Operates on the raw absolute distance, so compound leaps are not reduced to
+ * their simple class before the octave check.
+ *
+ * @param prev Starting pitch.
+ * @param cur Ending pitch.
+ * @returns True when the leap is forbidden in strict counterpoint.
+ * @category Voicing & Counterpoint
+ */
+declare function isForbiddenMelodicLeap(prev: number, cur: number): boolean;
+/**
+ * Whether two voices move into consecutive perfect intervals of the same kind
+ * (fifth-to-fifth, octave-to-octave, unison-to-unison).
+ *
+ * Both true parallels (similar motion) and anti-parallels — the same perfect
+ * class reached by contrary motion, e.g. octave to octave with the voices moving
+ * in opposite directions — are flagged, as both are forbidden in strict two-voice
+ * counterpoint. The rule requires that both voices actually move: oblique motion
+ * (either voice stationary) and the no-change case (identical pitches) are excluded.
+ *
+ * A fifth expanding to a twelfth counts (same perfect class); a fifth moving to
+ * an octave does not (different perfect kinds — the direct/hidden case owned by
+ * {@link createsHiddenParallelPerfect}).
+ *
+ * @category Voicing & Counterpoint
+ */
+declare function createsParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
+/**
+ * Whether two voices move in consecutive parallel octaves (or unisons) by
+ * similar motion.
+ *
+ * This is a strict subset of {@link createsParallelPerfect}: a similar-motion
+ * octave-to-octave is the perfect-class-zero case that predicate already flags
+ * (and it additionally catches the contrary-motion anti-parallel). Callers that
+ * tally parallel violations should therefore use {@link createsParallelPerfect}
+ * alone to avoid double counting; this predicate remains for callers wanting a
+ * dedicated similar-motion octave test.
+ *
+ * @category Voicing & Counterpoint
+ */
+declare function createsParallelOctave(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
+/**
+ * Whether two voices move in consecutive parallel unisons — both landing on the
+ * same pitch, having shared a pitch on the previous move.
+ *
+ * @category Voicing & Counterpoint
+ */
+declare function createsParallelUnison(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
+/**
+ * Whether two voices reach a perfect interval by similar motion from an
+ * imperfect one (a hidden/direct fifth or octave).
+ *
+ * The traditional step exception is applied: the approach is allowed when the
+ * upper of the two voices moves by step, so only leaps into the perfect
+ * interval are flagged.
+ *
+ * @category Voicing & Counterpoint
+ */
+declare function createsHiddenParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
+/**
+ * Whether two voices overlap: the upper voice descends below where the lower
+ * voice just was, or the lower voice rises above where the upper voice just was.
+ * Distinct from a simultaneous voice crossing.
+ *
+ * @param upperPrev Previous pitch of the upper voice.
+ * @param upperCur Current pitch of the upper voice.
+ * @param lowerPrev Previous pitch of the lower voice.
+ * @param lowerCur Current pitch of the lower voice.
+ * @category Voicing & Counterpoint
+ */
+declare function createsVoiceOverlap(upperPrev: number, upperCur: number, lowerPrev: number, lowerCur: number): boolean;
+/**
+ * Whether two adjacent upper voices are spaced more than a maximum apart
+ * (commonly an octave). Bass-to-tenor spacing is conventionally exempt, so this
+ * is meant for the upper voice pairs.
+ *
+ * @param upperPitch Pitch of the higher voice.
+ * @param lowerPitch Pitch of the lower voice.
+ * @param maxSemitones Maximum allowed spacing in semitones (default an octave).
+ * @category Voicing & Counterpoint
+ */
+declare function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemitones?: number): boolean;
+/**
+ * Whether a leading tone resolves correctly upward to the tonic.
+ *
+ * @param prev The leading-tone pitch.
+ * @param cur The following pitch.
+ * @param key Key context supplying the tonic.
+ * @returns True when `prev` is the leading tone and `cur` is the tonic a step above.
+ * @category Voicing & Counterpoint
+ */
+declare function isLeadingToneResolution(prev: number, cur: number, key: KeyScale): boolean;
+
+/**
+ * Test whether a pitch belongs to the scale.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param key The key/scale to test against.
+ * @returns True if the pitch class is a member of the scale.
+ *
+ * @example
+ * ```ts
+ * import { majorKey, isScaleTone } from '@libraz/libcantus';
+ * const key = majorKey(0); // C major
+ * isScaleTone(64, key); // true — E is in C major
+ * isScaleTone(61, key); // false — C# is not
+ * ```
+ *
+ * @category Scales
+ */
+declare function isScaleTone(pitch: number, key: KeyScale): boolean;
+/**
+ * Find the nearest MIDI pitch whose pitch class is in the scale.
+ *
+ * The search expands symmetrically outward from `pitch`. On a tie (equal
+ * distance above and below) the lower pitch is returned.
+ *
+ * @param pitch MIDI pitch to snap.
+ * @param key The key/scale to snap to.
+ * @returns The nearest in-scale MIDI pitch.
+ *
+ * @category Scales
+ */
+declare function nearestScaleTone(pitch: number, key: KeyScale): number;
+/**
+ * Get the 0-based scale degree of a pitch.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param key The key/scale to measure against.
+ * @returns The 0-based degree, or -1 if the pitch is not in the scale.
+ *
+ * @category Scales
+ */
+declare function pitchToScaleDegree(pitch: number, key: KeyScale): number;
+/**
+ * List the pitch classes of a key's scale.
+ *
+ * @param key The key/scale to enumerate.
+ * @returns The member pitch classes, sorted ascending in [0, 11].
+ *
+ * @category Scales
+ */
+declare function diatonicPitchClasses(key: KeyScale): number[];
+/**
+ * List the pitch classes of a key's scale in ascending scale-degree order.
+ *
+ * Degree 0 is the root; degrees follow the mask bits in offset order rather
+ * than sorted pitch-class order.
+ *
+ * @param key The key/scale to enumerate.
+ * @returns The member pitch classes ordered by scale degree.
+ *
+ * @category Scales
+ */
+declare function scaleTonesInDegreeOrder(key: KeyScale): number[];
+
+/**
+ * Build a `KeyScale` for a major key on the given root pitch class.
+ *
+ * @example
+ * ```ts
+ * import { majorKey } from '@libraz/libcantus';
+ * const cMajor = majorKey(0); // C major: { rootPc: 0, modeMask12: MAJOR_MASK }
+ * ```
+ *
+ * @category Scales
+ */
+declare function majorKey(rootPc: number): KeyScale;
+/**
+ * Build a `KeyScale` for a natural-minor key on the given root pitch class.
+ *
+ * @example
+ * ```ts
+ * import { minorKey } from '@libraz/libcantus';
+ * const aMinor = minorKey(9); // A natural minor: { rootPc: 9, modeMask12: NATURAL_MINOR_MASK }
+ * ```
+ *
+ * @category Scales
+ */
+declare function minorKey(rootPc: number): KeyScale;
+/**
+ * Build a `KeyScale` from a named scale (see {@link NAMED_SCALES}).
+ *
+ * @param name The scale name, e.g. `'dorian'` or `'harmonicMinor'`.
+ * @param rootPc The root pitch class.
+ * @returns The key/scale.
+ * @throws If the name is not a known scale.
+ *
+ * @example
+ * ```ts
+ * import { scaleByName } from '@libraz/libcantus';
+ * const dDorian = scaleByName('dorian', 2); // D Dorian, rootPc 2
+ * ```
+ *
+ * @category Scales
+ */
+declare function scaleByName(name: string, rootPc: number): KeyScale;
+
+/**
+ * Build a 12-bit mode mask from a list of semitone offsets above the root.
+ *
+ * Bit 0 (the root) is always set, enforcing the `KeyScale` invariant that the
+ * root is a scale tone even when the offset list omits 0.
+ *
+ * @category Scales
+ */
+declare function maskFromOffsets(offsets: readonly number[]): number;
+/**
+ * Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}.
+ *
+ * @category Scales
+ */
+declare const MAJOR_MASK = 2741;
+/**
+ * Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}.
+ *
+ * @category Scales
+ */
+declare const NATURAL_MINOR_MASK = 1453;
+/**
+ * Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}.
+ *
+ * @category Scales
+ */
+declare const HARMONIC_MINOR_MASK: number;
+/**
+ * Ascending melodic minor: offsets {0,2,3,5,7,9,11}.
+ *
+ * @category Scales
+ */
+declare const MELODIC_MINOR_MASK: number;
+/**
+ * Dorian mode: offsets {0,2,3,5,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const DORIAN_MASK: number;
+/**
+ * Phrygian mode: offsets {0,1,3,5,7,8,10}.
+ *
+ * @category Scales
+ */
+declare const PHRYGIAN_MASK: number;
+/**
+ * Lydian mode: offsets {0,2,4,6,7,9,11}.
+ *
+ * @category Scales
+ */
+declare const LYDIAN_MASK: number;
+/**
+ * Mixolydian mode: offsets {0,2,4,5,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const MIXOLYDIAN_MASK: number;
+/**
+ * Locrian mode: offsets {0,1,3,5,6,8,10}.
+ *
+ * @category Scales
+ */
+declare const LOCRIAN_MASK: number;
+/**
+ * Major pentatonic: offsets {0,2,4,7,9}.
+ *
+ * @category Scales
+ */
+declare const MAJOR_PENTATONIC_MASK: number;
+/**
+ * Minor pentatonic: offsets {0,3,5,7,10}.
+ *
+ * @category Scales
+ */
+declare const MINOR_PENTATONIC_MASK: number;
+/**
+ * Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}.
+ *
+ * @category Scales
+ */
+declare const BLUES_MASK: number;
+/**
+ * Whole-tone scale: offsets {0,2,4,6,8,10}.
+ *
+ * @category Scales
+ */
+declare const WHOLE_TONE_MASK: number;
+/**
+ * Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const OCTATONIC_HALF_WHOLE_MASK: number;
+/**
+ * Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}.
+ *
+ * @category Scales
+ */
+declare const OCTATONIC_WHOLE_HALF_MASK: number;
+/**
+ * Chromatic scale: all twelve pitch classes.
+ *
+ * @category Scales
+ */
+declare const CHROMATIC_MASK = 4095;
+/**
+ * Named scale masks addressable by {@link scaleByName}.
+ *
+ * @category Scales
+ */
+declare const NAMED_SCALES: Record<string, number>;
+
+/**
+ * Spelling: derive letter-name notes for scales and chords from a spelled tonic.
+ *
+ * The theory core works in pitch classes, which cannot choose between (say) a
+ * G# and an Ab. Given a spelled tonic, this module assigns diatonic letters to
+ * scale degrees and chord tones so a C major scale spells as C D E F G A B and
+ * A harmonic minor spells its seventh as G#.
+ */
+
+/**
+ * Spell a single pitch class relative to a spelled tonic and key.
+ *
+ * Diatonic pitch classes take the scale's letter for their degree; the common
+ * chromatic tones (b2, b3, #4, b6, b7) and a minor key's raised degrees (#6, #7)
+ * take their conventional, key-correct accidental spelling; anything else falls
+ * back to a sharp spelling of the nearest natural.
+ *
+ * @param pc The pitch class to spell.
+ * @param tonic The spelled tonic (its letter anchors the spelling).
+ * @param key The key/scale.
+ * @returns The spelled note (without octave).
+ * @category Pitch & Intervals
+ */
+declare function spellPitchClass(pc: number, tonic: Note, key: KeyScale): Note;
+/**
+ * Spell every pitch class of a scale, in ascending scale-degree order.
+ *
+ * Correct for heptatonic scales (each degree gets the next letter). Non-standard
+ * scales are spelled tone-by-tone with a sharp preference.
+ *
+ * @param tonic The spelled tonic.
+ * @param key The key/scale.
+ * @returns Spelled notes, one per scale degree.
+ * @example
+ * ```ts
+ * import { spellScale, noteNames, parseNote, majorKey } from '@libraz/libcantus';
+ * noteNames(spellScale(parseNote('C'), majorKey(0)));
+ * // ['C', 'D', 'E', 'F', 'G', 'A', 'B']
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function spellScale(tonic: Note, key: KeyScale): Note[];
+/**
+ * Spell an arbitrary list of pitch classes relative to a key.
+ *
+ * @param pcs The pitch classes.
+ * @param tonic The spelled tonic.
+ * @param key The key/scale.
+ * @returns Spelled notes, in input order.
+ * @category Pitch & Intervals
+ */
+declare function spellPitchClasses(pcs: number[], tonic: Note, key: KeyScale): Note[];
+/**
+ * Spell a chord's tones, in the chord's own (tertian) order, relative to a key.
+ *
+ * Diatonic chords spell exactly (e.g. G7 in C major -> G B D F). Chromatic chord
+ * tones take their conventional spelling; enharmonically ambiguous altered
+ * tensions may be spelled by the general convention rather than by chord
+ * function.
+ *
+ * @param chord The chord.
+ * @param tonic The spelled tonic of the key.
+ * @param key The key/scale.
+ * @returns Spelled chord tones, root first.
+ * @example
+ * ```ts
+ * import { spellChord, noteNames, parseNote, majorKey, makeChord } from '@libraz/libcantus';
+ * // G7 in C major
+ * noteNames(spellChord(makeChord(7, 'dom7'), parseNote('C'), majorKey(0)));
+ * // ['G', 'B', 'D', 'F']
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[];
+/**
+ * Convenience: render spelled notes as letter-name strings.
+ *
+ * @param notes The notes.
+ * @returns Their formatted names.
+ * @category Pitch & Intervals
+ */
+declare function noteNames(notes: Note[]): string[];
+
+/**
+ * Lead-sheet chord symbol parsing and formatting.
+ *
+ * Bridges the informal `<root><quality>[/<bass>]` notation musicians write
+ * (`Cmaj7`, `F#m7b5`, `Bb7`, `C/G`) and the library's structured {@link Chord}
+ * type, so callers can accept/emit plain text at the edges of the API.
+ */
+
+/**
+ * Parse a lead-sheet chord symbol into a {@link Chord}.
+ *
+ * Accepts `<root><quality>[/<bass>]`, e.g. `Cmaj7`, `F#m7b5`, `Bb7`, `C/G`,
+ * `C6/9`, `C6/9/E`. Root and bass letters are case-insensitive, matching
+ * {@link parseNote}. A `/` is ambiguous between a slash bass and the `6/9`
+ * quality; the text splits at the last `/` whose right-hand side is a valid
+ * bare note preceded by a recognized quality, so `6/9` (with or without a
+ * further slash bass) parses as a quality.
+ *
+ * The parsed chord carries the root/bass spellings as enharmonic hints
+ * (`rootSpelling`/`bassSpelling`) so {@link formatChordSymbol} can reproduce
+ * flat spellings such as `Bbmaj7` instead of respelling them with sharps.
+ *
+ * @param text The chord symbol text.
+ * @returns The parsed chord.
+ * @throws If the root or quality is not recognized.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, formatChordSymbol } from '@libraz/libcantus';
+ * const c = parseChordSymbol('Bbmaj7');
+ * formatChordSymbol(c); // 'Bbmaj7' — flat spelling is preserved on round-trip
+ * ```
+ * @category Chords
+ */
+declare function parseChordSymbol(text: string): Chord;
+/**
+ * Format a {@link Chord} as a lead-sheet chord symbol.
+ *
+ * The inverse of {@link parseChordSymbol}: each quality maps to one canonical
+ * suffix spelling, and a slash bass is appended only when it differs from the
+ * root. When the chord carries `rootSpelling`/`bassSpelling` hints (as chords
+ * from {@link parseChordSymbol} do) and no explicit `flats` preference is
+ * given, the hints are reused so flat symbols round-trip unchanged.
+ *
+ * @param chord The chord to format.
+ * @param opts Formatting options.
+ * @param opts.flats Prefer flat spellings over sharps for altered roots/basses;
+ *   passing either `true` or `false` overrides any spelling hints.
+ * @returns The chord symbol text.
+ * @example
+ * ```ts
+ * import { makeChord, formatChordSymbol } from '@libraz/libcantus';
+ * formatChordSymbol(makeChord(0, 'min7')); // 'Cm7'
+ * ```
+ * @category Chords
+ */
+declare function formatChordSymbol(chord: Chord, opts?: {
+    flats?: boolean;
+}): string;
+/**
+ * Transpose a chord symbol by a number of semitones.
+ *
+ * @param text The chord symbol text.
+ * @param semitones Signed semitone offset to apply to the root and bass.
+ * @param opts Formatting options for the result; see {@link formatChordSymbol}.
+ * @returns The transposed chord symbol text.
+ * @throws If `text` does not parse as a chord symbol.
+ * @example
+ * ```ts
+ * import { transposeChordSymbol } from '@libraz/libcantus';
+ * transposeChordSymbol('C/G', 2); // 'D/A'
+ * ```
+ * @category Chords
+ */
+declare function transposeChordSymbol(text: string, semitones: number, opts?: {
+    flats?: boolean;
+}): string;
+
+export { BLUES_MASK, CHROMATIC_MASK, Chord as ChordData, DORIAN_MASK, HARMONIC_MINOR_MASK, LOCRIAN_MASK, LYDIAN_MASK, MAJOR_MASK, MAJOR_PENTATONIC_MASK, MELODIC_MINOR_MASK, MINOR_PENTATONIC_MASK, MIXOLYDIAN_MASK, NAMED_SCALES, NATURAL_MINOR_MASK, OCTATONIC_HALF_WHOLE_MASK, OCTATONIC_WHOLE_HALF_MASK, PHRYGIAN_MASK, VoicingOptions, WHOLE_TONE_MASK, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, formatChordSymbol, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, maskFromOffsets, minorKey, nearestScaleTone, nextVoicing, noteNames, parseChordSymbol, pitchToScaleDegree, scaleByName, scaleTonesInDegreeOrder, spellChord, spellPitchClass, spellPitchClasses, spellScale, transposeChordSymbol, voiceLeadingCost };