@libraz/libcantus 0.9.1 → 0.9.2

package/dist/generate/index.js

@@ -0,0 +1,52 @@
+import {
+  applyGrooveTemplate,
+  developMotif,
+  extractGrooveTemplate,
+  generateBassLine,
+  generateCounterMelody,
+  generateDrums,
+  generateMotif,
+  generateProgression,
+  generateRhythm,
+  harmonizeMelody,
+  humanize,
+  onsetWeightCurve,
+  progressions,
+  progressionsByStyle,
+  rhythmDensity,
+  transformMotif
+} from "../chunk-R3S2LUBH.js";
+import "../chunk-BHUT2S5G.js";
+import "../chunk-MSWFZF7J.js";
+import {
+  modalInterchangePalette,
+  negativeHarmonyMirror,
+  substituteChord
+} from "../chunk-GQKN5KDT.js";
+import "../chunk-LN7ZZMD2.js";
+import "../chunk-SDM3VJJ5.js";
+import "../chunk-A4532ZFR.js";
+import "../chunk-7Y7WF64D.js";
+import "../chunk-CCBLVAPK.js";
+export {
+  applyGrooveTemplate,
+  developMotif,
+  extractGrooveTemplate,
+  generateBassLine,
+  generateCounterMelody,
+  generateDrums,
+  generateMotif,
+  generateProgression,
+  generateRhythm,
+  harmonizeMelody,
+  humanize,
+  modalInterchangePalette,
+  negativeHarmonyMirror,
+  onsetWeightCurve,
+  progressions,
+  progressionsByStyle,
+  rhythmDensity,
+  substituteChord,
+  transformMotif
+};
+//# sourceMappingURL=index.js.map

package/dist/generate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index-BMPxwjwV.d.ts

@@ -0,0 +1,151 @@
+import { T as TimeSignature } from './index-Cl7mhOFM.js';
+import { K as KeyScale, N as NoteEvent } from './types-MGP29r3t.js';
+import { C as Chord, b as ChordSpan } from './index-CM5W4rcm.js';
+import { C as Cadence } from './function-2bJW1Zp_.js';
+
+/**
+ * A chord occupying a half-open beat span.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordSegment = {
+    startBeat: number;
+    endBeat: number;
+    chord: Chord;
+};
+/**
+ * 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: ChordSpan[], totalBeats: number): ChordTimeline;
+/**
+ * Options controlling {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordTimelineOptions = {
+    /** Key context; inferred from the notes with {@link detectKey} 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;
+};
+/**
+ * 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 ChordSegment as a, type ChordTimeline as b, type ChordTimelineOptions as c, type ChordTimelineResult as d, chordTimelineFromChords as e, chordTimelineFromNotes as f, detectCadences as g };

package/dist/index-BOBXBNwP.d.cts

@@ -0,0 +1,157 @@
+import { K as KeyScale } from './types-MGP29r3t.cjs';
+
+/**
+ * Chord quality identifiers understood by the chord builder.
+ *
+ * @category Chords
+ */
+type ChordQuality = 'maj' | 'min' | 'dim' | 'aug' | 'maj7' | 'min7' | 'dom7' | 'dim7' | 'm7b5' | 'minMaj7' | 'aug7' | 'augMaj7' | 'majb5' | '6' | 'min6' | '6/9' | 'sus2' | 'sus4' | 'add9' | 'add11' | 'maj9' | 'min9' | 'dom9' | '7b9' | '7#9' | '7#11' | '7b13' | '11' | '13' | '5';
+/**
+ * A bare spelled pitch used as an enharmonic hint: a diatonic letter
+ * (0..6 = C..B) plus a chromatic alteration (-2 double-flat .. +2 double-sharp).
+ * Mirrors the letter/alter half of the pitch module's `Note` without an octave.
+ *
+ * @category Chords
+ */
+type PitchSpelling = {
+    letter: number;
+    alter: number;
+};
+/**
+ * A chord expressed as a root pitch class plus semitone offsets.
+ *
+ * `rootSpelling`/`bassSpelling` are optional enharmonic hints recorded by
+ * parsers (e.g. `parseChordSymbol('Bb7')`) so formatters can reproduce the
+ * original spelling instead of defaulting to sharps. Consumers may ignore
+ * them; a hint is only trusted when its pitch class still matches the
+ * corresponding `rootPc`/`bassPc`.
+ *
+ * @category Chords
+ */
+type Chord = {
+    rootPc: number;
+    quality: ChordQuality;
+    intervals: number[];
+    bassPc?: number;
+    rootSpelling?: PitchSpelling;
+    bassSpelling?: PitchSpelling;
+};
+/**
+ * A chord positioned in time: a root pitch class and quality placed at a beat,
+ * with optional harmonic-analysis hints. Serves as the neutral exchange record
+ * between progression generators and timeline analysers.
+ *
+ * @category Composition
+ */
+type ChordSpan = {
+    rootPc: number;
+    quality: ChordQuality;
+    startBeat: number;
+    bassPc?: number;
+    /** 0-based scale degree of the chord root, when known. */
+    degree?: number;
+    /** True when the chord is a secondary dominant tonicizing another degree. */
+    secondaryDominant?: boolean;
+};
+/**
+ * All chord qualities the builder understands, longest templates last.
+ *
+ * @category Chords
+ */
+declare function chordQualities(): ChordQuality[];
+/**
+ * Build a chord rooted on a diatonic scale degree.
+ *
+ * The root pitch class is the degree's diatonic pitch class in `key`; the
+ * quality's interval template is attached unchanged. Degrees beyond the scale
+ * length wrap around.
+ *
+ * @param degree 0-based scale degree of the chord root.
+ * @param ext Chord quality to apply.
+ * @param key Key context supplying the diatonic root.
+ * @returns The constructed chord.
+ *
+ * @category Chords
+ */
+declare function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale): Chord;
+/**
+ * Build a chord from an explicit root pitch class and quality.
+ *
+ * @param rootPc Root pitch class (0..11).
+ * @param quality Chord quality supplying the interval template.
+ * @param bassPc Optional slash-chord bass pitch class.
+ * @returns The constructed chord.
+ *
+ * @example
+ * ```ts
+ * import { makeChord } from '@libraz/libcantus';
+ * const cmaj7 = makeChord(0, 'maj7');
+ * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
+ * ```
+ *
+ * @category Chords
+ */
+declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord;
+/**
+ * Get the sorted, deduplicated pitch classes of a chord.
+ *
+ * @param chord The chord to enumerate.
+ * @returns The chord's pitch classes, sorted ascending in [0, 11].
+ *
+ * @example
+ * ```ts
+ * import { makeChord, chordPitchClasses } from '@libraz/libcantus';
+ * chordPitchClasses(makeChord(0, 'maj7')); // [0, 4, 7, 11]
+ * ```
+ *
+ * @category Chords
+ */
+declare function chordPitchClasses(chord: Chord): number[];
+/**
+ * Determine a pitch's harmonic role within a chord.
+ *
+ * The role is derived from the pitch's interval above the chord root, reduced
+ * modulo 12. A major sixth (9) reads as a `sixth` for sixth chords but as a
+ * `seventh` for a diminished-seventh chord; ninths and other tensions have no
+ * basic role and return null.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord providing the root reference.
+ * @returns The chord-tone role, or null if the pitch has no basic role.
+ *
+ * @category Chords
+ */
+declare function chordToneRole(pitch: number, chord: Chord): 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | null;
+/**
+ * Build the diatonic triad rooted on a scale degree by stacking scale thirds.
+ *
+ * Unlike {@link chordFromDegree}, the chord quality is derived from the scale
+ * rather than supplied, so degrees yield their scale-correct triads (e.g. a
+ * diminished triad on the leading tone of a major key). Intended for heptatonic
+ * scales; other scales stack by scale step regardless.
+ *
+ * @param degree 0-based scale degree of the chord root.
+ * @param key Key/scale context.
+ * @returns The diatonic triad.
+ *
+ * @example
+ * ```ts
+ * import { majorKey, diatonicTriad } from '@libraz/libcantus';
+ * const tonic = diatonicTriad(0, majorKey(0)); // C major triad (degree 0 of C major)
+ * ```
+ *
+ * @category Chords
+ */
+declare function diatonicTriad(degree: number, key: KeyScale): Chord;
+/**
+ * Build the diatonic seventh chord rooted on a scale degree.
+ *
+ * @param degree 0-based scale degree of the chord root.
+ * @param key Key/scale context.
+ * @returns The diatonic seventh chord.
+ *
+ * @category Chords
+ */
+declare function diatonicSeventh(degree: number, key: KeyScale): Chord;
+
+export { type Chord as C, type ChordQuality as a, type ChordSpan as b, chordFromDegree as c, chordPitchClasses as d, chordQualities as e, chordToneRole as f, diatonicSeventh as g, diatonicTriad as h, makeChord as m };

package/dist/index-BdeQ1r_p.d.cts

@@ -0,0 +1,56 @@
+import { C as Chord } from './index-BOBXBNwP.cjs';
+
+/**
+ * Harmonic role a pitch plays within a chord.
+ *
+ * @category Functional Harmony
+ */
+type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension' | 'doubling';
+/**
+ * How firmly a pitch is locked to the chord's identity.
+ *
+ * - `identity`: moving it produces a different chord (the root).
+ * - `quality`: moving it flips the chord quality (the third).
+ * - `voicing`: it can move freely without changing chord identity or quality.
+ *
+ * @category Functional Harmony
+ */
+type LockLevel = 'identity' | 'quality' | 'voicing';
+/**
+ * A pitch's role, lock level, and owning chord.
+ *
+ * @category Functional Harmony
+ */
+type VoicedRole = {
+    role: HarmonyRole;
+    lock: LockLevel;
+    belongsToChordId: number;
+};
+/**
+ * Classify a pitch's harmonic role and lock level within a chord.
+ *
+ * The role comes from the pitch's interval class above the chord root: root (0),
+ * third (3/4), fifth (6/7/8), seventh (10/11), and 9/11/13 tensions (2/5/9, and
+ * the flat ninth 1). The root locks the chord identity, the third locks its
+ * quality, and everything else is free voicing. In a suspended chord (a chord
+ * whose intervals include a 4th (5) or 2nd (2) but no third), the suspended tone
+ * takes the third's place as the quality-defining tone and is locked to
+ * `quality`, since moving it changes the chord. Detecting an octave doubling
+ * requires the surrounding voicing, which this single-pitch query does not carry,
+ * so `doubling` is part of the type but not returned here.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord providing the root reference.
+ * @param chordId Identifier stored on the result (defaults to 0).
+ * @returns The pitch's role, lock level, and owning chord id.
+ * @example
+ * ```ts
+ * import { roleOf, makeChord } from '@libraz/libcantus';
+ * roleOf(64, makeChord(0, 'maj')); // E over C major
+ * // { role: 'third', lock: 'quality', belongsToChordId: 0 }
+ * ```
+ * @category Functional Harmony
+ */
+declare function roleOf(pitch: number, chord: Chord, chordId?: number): VoicedRole;
+
+export { type HarmonyRole as H, type LockLevel as L, type VoicedRole as V, roleOf as r };

package/dist/index-BreoJRw0.d.ts

@@ -0,0 +1,127 @@
+import { K as KeyScale } from './types-MGP29r3t.js';
+import { C as Chord } from './index-CM5W4rcm.js';
+
+/**
+ * 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
+}
+/**
+ * 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): SafetyResult;
+/**
+ * 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.
+ * @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 { 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-CGMZNCx6.d.cts

@@ -0,0 +1,140 @@
+/**
+ * Pitch spelling: letter-name notes, enharmonic-aware conversion, and spelled
+ * intervals.
+ *
+ * The rest of the library works in pitch classes (0..11), which cannot tell a
+ * G# from an Ab or an augmented fourth from a diminished fifth. This module adds
+ * an explicit spelling layer — a note is a diatonic letter plus a chromatic
+ * alteration — so interval quality (P/M/m/A/d) and enharmonic identity are
+ * preserved.
+ */
+/**
+ * A spelled note: a diatonic letter, a chromatic alteration, and an optional
+ * octave.
+ *
+ * - `letter` is 0..6 for C..B.
+ * - `alter` is the number of semitones of alteration: -2 double-flat, -1 flat,
+ *   0 natural, +1 sharp, +2 double-sharp.
+ * - `octave` follows scientific pitch notation (middle C = C4 = MIDI 60). When
+ *   absent, the note denotes a bare pitch class.
+ *
+ * @category Pitch & Intervals
+ */
+type Note = {
+    letter: number;
+    alter: number;
+    octave?: number;
+};
+/**
+ * A spelled interval: a diatonic number, a quality label, and its semitone span.
+ *
+ * @category Pitch & Intervals
+ */
+type SpelledInterval = {
+    /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
+    number: number;
+    /** Quality label: 'P', 'M', 'm', or repeated 'A'/'d' for (multiply) aug/dim. */
+    quality: string;
+    /** Signed semitone distance from the first note to the second. */
+    semitones: number;
+};
+/**
+ * Parse scientific pitch notation into a {@link Note}.
+ *
+ * Accepts a letter (case-insensitive) followed by any number of same-direction
+ * accidentals and an optional octave, e.g. `"C"`, `"C#4"`, `"Bb"`, `"F##3"`,
+ * `"Ebb2"`. Both `#` and `x` (double-sharp) are accepted for sharps; `b` for
+ * flats. Mixing sharps and flats (e.g. `"C#b"`) is rejected.
+ *
+ * @param text The note text.
+ * @returns The parsed note.
+ * @throws If the text is not a valid note.
+ * @example
+ * ```ts
+ * import { parseNote, noteToMidi } from '@libraz/libcantus';
+ * const n = parseNote('C#4');
+ * noteToMidi(n); // 61
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function parseNote(text: string): Note;
+/**
+ * Render a {@link Note} as scientific pitch notation.
+ *
+ * @param note The note to format.
+ * @returns The note text, including the octave when present.
+ * @example
+ * ```ts
+ * import { formatNote, parseNote } from '@libraz/libcantus';
+ * formatNote(parseNote('C#4')); // 'C#4'
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function formatNote(note: Note): string;
+/**
+ * Pitch class (0..11) of a note, ignoring octave.
+ *
+ * @param note The note.
+ * @returns The pitch class.
+ * @example
+ * ```ts
+ * import { noteToPitchClass, parseNote } from '@libraz/libcantus';
+ * noteToPitchClass(parseNote('Db')); // 1
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function noteToPitchClass(note: Note): number;
+/**
+ * MIDI number of a note (middle C = C4 = 60).
+ *
+ * @param note The note; must carry an octave.
+ * @returns The MIDI number.
+ * @throws If the note has no octave.
+ * @example
+ * ```ts
+ * import { noteToMidi, parseNote } from '@libraz/libcantus';
+ * noteToMidi(parseNote('A4')); // 69
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function noteToMidi(note: Note): number;
+/**
+ * Name a MIDI number as a {@link Note}, choosing sharp or flat spelling.
+ *
+ * The input is rounded to the nearest integer but is not clamped to the MIDI
+ * range 0..127: out-of-range values extrapolate linearly (e.g. `-1` -> `B-2`,
+ * `128` -> `G#9`) and remain an exact inverse of {@link noteToMidi}.
+ *
+ * @param midi The MIDI number.
+ * @param spelling Whether to prefer sharps or flats for black keys.
+ * @returns The spelled note, with octave.
+ * @example
+ * ```ts
+ * import { midiToNote, formatNote } from '@libraz/libcantus';
+ * formatNote(midiToNote(61)); // 'C#4'
+ * formatNote(midiToNote(61, 'flat')); // 'Db4'
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function midiToNote(midi: number, spelling?: 'sharp' | 'flat'): Note;
+/**
+ * The spelled interval from one note to another.
+ *
+ * When both notes carry octaves, the interval reflects their full signed
+ * distance (so `C4 -> C5` is a perfect octave). When either lacks an octave the
+ * interval is measured within a single ascending octave from `a` to `b`.
+ *
+ * @param a The lower/first note.
+ * @param b The upper/second note.
+ * @returns The diatonic number, quality, and semitone span.
+ * @example
+ * ```ts
+ * import { spelledInterval, parseNote } from '@libraz/libcantus';
+ * spelledInterval(parseNote('C4'), parseNote('G4'));
+ * // { number: 5, quality: 'P', semitones: 7 }
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function spelledInterval(a: Note, b: Note): SpelledInterval;
+
+export { type Note as N, type SpelledInterval as S, noteToPitchClass as a, formatNote as f, midiToNote as m, noteToMidi as n, parseNote as p, spelledInterval as s };