@libraz/libcantus 0.9.0 → 0.9.2

package/dist/index.d.ts

@@ -1,2621 +1,14 @@
-/**
- * A key/scale definition anchored on a root pitch class.
- *
- * `modeMask12` is a 12-bit mask where bit `n` set means the pitch class
- * `(rootPc + n) % 12` belongs to the scale. Bit 0 (the root) is always set;
- * {@link maskFromOffsets} enforces this so the root is always a scale tone.
- */
-type KeyScale = {
-    rootPc: number;
-    modeMask12: number;
-};
-/**
- * A single sounding note on a beat-indexed timeline: an absolute MIDI pitch, an
- * onset and duration measured in quarter-note beats, and an optional MIDI
- * velocity. This is the library-wide interchange shape for note events read
- * from or written to a DAW/MIDI track; the harmonizer's `MelodyNote` and the
- * analysis `VoiceNote` are specializations of it.
- */
-type NoteEvent = {
-    /** MIDI pitch (middle C = 60). */
-    pitch: number;
-    /** Onset in quarter-note beats, absolute from the start of the timeline. */
-    startBeat: number;
-    /** Duration in quarter-note beats. */
-    durationBeat: number;
-    /** MIDI velocity in [0, 127], when known. */
-    velocity?: number;
-};
-
-/** Chord quality identifiers understood by the chord builder. */
-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 chord expressed as a root pitch class plus semitone offsets. */
-type Chord$1 = {
-    rootPc: number;
-    quality: ChordQuality;
-    intervals: number[];
-    bassPc?: number;
-};
-/** All chord qualities the builder understands, longest templates last. */
-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.
- */
-declare function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale): Chord$1;
-/**
- * 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.
- */
-declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord$1;
-/**
- * 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].
- */
-declare function chordPitchClasses(chord: Chord$1): 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.
- */
-declare function chordToneRole(pitch: number, chord: Chord$1): '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.
- */
-declare function diatonicTriad(degree: number, key: KeyScale): Chord$1;
-/**
- * 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.
- */
-declare function diatonicSeventh(degree: number, key: KeyScale): Chord$1;
-
-/** Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading. */
-type SafetyProfile = 'strict' | 'pop';
-/** Overall placeability verdict for a candidate pitch. */
-declare enum NoteSafety {
-    Safe = 0,
-    Warning = 1,
-    Dissonant = 2
-}
-/** Bit flags describing why a pitch received its verdict. */
-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. */
-type VoiceSnapshot = {
-    pitch: number;
-    prevPitch?: number;
-};
-/** Everything needed to evaluate one candidate pitch. */
-type SafetyQuery = {
-    profile: SafetyProfile;
-    candidatePitch: number;
-    prevPitch?: number;
-    chord: Chord$1 | null;
-    key: KeyScale;
-    otherVoices: VoiceSnapshot[];
-    strongBeat: boolean;
-    vocalLow?: number;
-    vocalHigh?: number;
-};
-/** The verdict, reason flags, and optional resolution guidance. */
-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.
- */
-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.
- */
-declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
-
-/** A theory annotation attached to a note. */
-type TheoryLabel = {
-    kind: 'chordTone';
-    role: 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
-} | {
-    kind: 'tension';
-    degree: 9 | 11 | 13;
-} | {
-    kind: 'avoid';
-} | {
-    kind: 'passing';
-} | {
-    kind: 'neighbor';
-} | {
-    kind: 'suspension';
-    type: 'sus4-3' | 'sus7-6' | 'sus9-8' | 'sus2-3';
-    resolveTo: number;
-} | {
-    kind: 'anticipation';
-} | {
-    kind: 'escape';
-} | {
-    kind: 'needsResolution';
-    resolveTo: number;
-} | {
-    kind: 'leadingTone';
-    resolveTo: number;
-};
-/** A note with its theory labels and a short rationale. */
-type AnalyzedNote = {
-    noteId: number;
-    labels: TheoryLabel[];
-    rationale?: string;
-};
-/** A single note in a monophonic voice: a {@link NoteEvent} with a stable id. */
-type VoiceNote = NoteEvent & {
-    id: number;
-};
-/**
- * Label every note of a voice with its theory roles.
- *
- * Each note is classified against the chord sounding at its beat. Chord tones
- * get a role label; non-chord tones are matched, in order, as suspensions
- * (prepared by an identical consonant pitch and resolving by step), passing
- * tones, neighbors, anticipations, and escape tones, then fall back to tension,
- * avoid, or an unresolved-dissonance label. Leading-tone resolutions are noted
- * additionally.
- *
- * @param voice The monophonic voice, in time order.
- * @param chordAtBeat Chord sounding at a given beat, or null.
- * @param key Key context for leading-tone detection.
- * @param otherVoicesAtBeat Other sounding voices at a given beat.
- * @returns One annotation per input note.
- */
-declare function analyzeVoice(voice: VoiceNote[], chordAtBeat: (beat: number) => Chord$1 | null, key: KeyScale, otherVoicesAtBeat: (beat: number) => VoiceSnapshot[]): AnalyzedNote[];
-
-/**
- * Meter and time signatures: bar/beat arithmetic, simple vs. compound meters,
- * metric-accent hierarchy, and tuplet subdivision.
- *
- * Positions and durations are measured in quarter-note beats, matching the rest
- * of the library's beat convention (four quarter-note beats per bar in 4/4).
- */
-/** A time signature as a numerator over a note-value denominator. */
-type TimeSignature = {
-    numerator: number;
-    denominator: number;
-};
-/** A position expressed as a bar index and a quarter-note offset within the bar. */
-type BarPosition = {
-    bar: number;
-    /** Quarter-note offset from the start of the bar. */
-    beat: number;
-};
-/**
- * Parse a time signature such as `"4/4"` or `"6/8"`.
- *
- * @param text The signature text.
- * @returns The parsed time signature.
- * @throws If the text is not `n/d` with positive integers.
- */
-declare function parseTimeSignature(text: string): TimeSignature;
-/** Render a time signature as `"n/d"`. */
-declare function formatTimeSignature(ts: TimeSignature): string;
-/**
- * Whether a meter is compound: its main pulses each divide into three, as in
- * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a
- * multiple of three greater than three, independent of the denominator. Meters
- * like 3/8 and 3/4 (simple triples, numerator 3) are not compound.
- *
- * @param ts The time signature.
- * @returns True for compound meters.
- */
-declare function isCompound(ts: TimeSignature): boolean;
-/**
- * Length of a bar in quarter-note beats.
- *
- * @param ts The time signature.
- * @returns The bar length in quarter notes.
- */
-declare function beatsPerBar(ts: TimeSignature): number;
-/**
- * Number of main pulses (felt beats) per bar: the numerator for simple meters,
- * a third of it for compound meters.
- *
- * @param ts The time signature.
- * @returns The pulse count per bar.
- */
-declare function pulsesPerBar(ts: TimeSignature): number;
-/**
- * Convert an absolute quarter-note position to a bar index and in-bar offset.
- *
- * @param beatInQuarters Absolute position in quarter-note beats.
- * @param ts The time signature.
- * @returns The bar and in-bar quarter-note offset.
- */
-declare function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition;
-/**
- * Convert a bar index and in-bar offset back to an absolute quarter-note
- * position.
- *
- * @param pos The bar position.
- * @param ts The time signature.
- * @returns The absolute position in quarter-note beats.
- */
-declare function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number;
-/**
- * Metric weight of a position within its bar, on a 0–3 scale:
- * 3 the downbeat, 2 a secondary strong pulse (the bar's midpoint in even
- * meters), 1 any other main pulse, and 0 an off-pulse subdivision.
- *
- * @param beatInQuarters Absolute or in-bar quarter-note position.
- * @param ts The time signature.
- * @returns The metric weight (0–3).
- */
-declare function metricWeight(beatInQuarters: number, ts: TimeSignature): number;
-/**
- * Whether a position is metrically accented (weight 2 or more — a downbeat or a
- * secondary strong pulse).
- *
- * @param beatInQuarters Absolute or in-bar quarter-note position.
- * @param ts The time signature.
- * @returns True on strong beats.
- */
-declare function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean;
-/**
- * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note
- * triplet is `tuplet(1, 3)`).
- *
- * @param totalBeats Total span in quarter-note beats.
- * @param count Number of equal parts.
- * @returns `count` equal durations summing to `totalBeats`.
- * @throws If `count` is not a positive integer.
- */
-declare function tuplet(totalBeats: number, count: number): number[];
-
-/**
- * Functional harmony: Roman-numeral parsing and formatting, harmonic function
- * (tonic / subdominant / dominant), and cadence detection.
- *
- * 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. */
-type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
-/** A recognized cadence type, or null when a chord pair forms none. */
-type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
-/** Whether a key's scale has a minor third and no major third (a minor key). */
-declare function isMinorKey(key: KeyScale): boolean;
-/**
- * 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. Root-position extension
- * figures map to fixed qualities (`V9` -> `dom9`, `V11` -> `11`, `V13` -> `13`).
- * A figure string that is neither a recognized inversion nor a supported
- * extension throws rather than silently degrading to a triad.
- *
- * @param text The Roman numeral.
- * @param key The prevailing key.
- * @returns The chord.
- */
-declare function romanToChord(text: string, key: KeyScale): Chord$1;
-/**
- * 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. When the chord carries a `bassPc` on a chord tone, a figured-bass
- * inversion (`6`, `64`, `65`, `43`, `42`) is emitted.
- *
- * @param chord The chord to name.
- * @param key The prevailing key.
- * @returns The Roman numeral string.
- */
-declare function chordToRoman(chord: Chord$1, key: KeyScale): string;
-/**
- * The harmonic function of a chord in a key, from its root's offset above the
- * tonic. The mapping follows common-practice major-key function and is a useful
- * approximation in minor and for borrowed chords.
- *
- * @param chord The chord.
- * @param key The prevailing key.
- * @returns The harmonic function.
- */
-declare function functionOf(chord: Chord$1, key: KeyScale): HarmonicFunction;
-/** The origin of a recognized non-diatonic chord, or null when none applies. */
-type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
-/** The result of {@link analyzeChord}: function, borrowing, and Roman numeral. */
-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.
- */
-declare function isDiatonic(chord: Chord$1, 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.
- */
-declare function parallelKey(key: KeyScale): KeyScale;
-/**
- * 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 harmonic minor scale (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.
- */
-declare function isBorrowedChord(chord: Chord$1, 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, harmonic-minor alterations,
- * and unrecognized chromatic chords all yield null.
- *
- * @param chord The chord to classify.
- * @param key The prevailing key.
- * @returns The borrowing source, or null.
- */
-declare function borrowedSource(chord: Chord$1, key: KeyScale): BorrowedSource;
-/**
- * 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.
- * @returns The chord analysis.
- */
-declare function analyzeChord(chord: Chord$1, key: KeyScale): ChordAnalysis;
-/**
- * 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.
- */
-declare function detectCadence(from: Chord$1, to: Chord$1, key: KeyScale): Cadence;
-/**
- * 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.
- */
-declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord$1;
-
-/** Broad production style a progression preset suits. */
-type ProgStyle = 'minimal' | 'dance' | 'idol' | 'rock';
-/** Harmonic-function role of a progression as a whole. */
-type ProgFunction = 'loop' | 'tensionBuild' | 'cadenceStrong' | 'stable';
-/** A named chord-progression preset expressed in scale degrees. */
-type ProgressionPreset = {
-    id: string;
-    name: string;
-    degrees: number[];
-    functional: ProgFunction;
-    styles: ProgStyle[];
-};
-/** A chord placed on the timeline by {@link generateProgression}. */
-type GeneratedChord = {
-    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;
-};
-/** Options controlling {@link generateProgression}. */
-type GenerateProgressionOptions = {
-    key: KeyScale;
-    style: ProgStyle;
-    bars: number;
-    presetId?: string;
-    ext?: ChordQuality | 'auto';
-    reharmonize?: boolean;
-    seed?: number;
-};
-/** All built-in progression presets. */
-declare function progressions(): ProgressionPreset[];
-/** Presets whose style list includes the given style. */
-declare function progressionsByStyle(style: ProgStyle): ProgressionPreset[];
-/**
- * Generate a chord progression laid out one chord per bar.
- *
- * A preset is chosen by `presetId` when given, otherwise deterministically from
- * the presets matching `style`, seeded by `seed`. The preset's degrees cycle to
- * fill `bars`; each bar is four beats, so `startBeat` is `barIndex * 4`. Chord
- * roots come from the key's diatonic scale-degree mapping. When `ext` is
- * omitted or `'auto'`, each chord takes its diatonic triad quality; otherwise
- * `ext` is forced on every chord. When `reharmonize` is set, some chords are
- * deterministically replaced with the secondary dominant (V7) of the following
- * chord, flagged with `secondaryDominant`.
- *
- * @param opts Generation options.
- * @returns One chord per bar in timeline order.
- */
-declare function generateProgression(opts: GenerateProgressionOptions): GeneratedChord[];
-
-/** A chord occupying a half-open beat span. */
-type ChordSegment = {
-    startBeat: number;
-    endBeat: number;
-    chord: Chord$1;
-};
-/** A beat-indexed sequence of chord segments. */
-type ChordTimeline = {
-    /** The chord sounding at a beat, or null when no segment covers it. */
-    at: (beat: number) => Chord$1 | 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.
- */
-declare function chordTimelineFromChords(chords: GeneratedChord[], totalBeats: number): ChordTimeline;
-/** Options controlling {@link chordTimelineFromNotes}. */
-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. */
-    ts?: TimeSignature;
-    /** Window length in beats per chord slot; defaults to one bar of `ts`. */
-    harmonicRhythm?: number;
-    /** End of the analyzed span in beats; defaults to the end of the last note. */
-    totalBeats?: number;
-};
-/** The result of {@link chordTimelineFromNotes}. */
-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.
- *
- * @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.
- */
-declare function chordTimelineFromNotes(notes: NoteEvent[], opts?: ChordTimelineOptions): ChordTimelineResult;
-/** A cadence found between two consecutive timeline segments. */
-type CadenceHit = {
-    /** The beat where the cadence arrives (the second chord's onset). */
-    atBeat: number;
-    type: Exclude<Cadence, null>;
-    from: Chord$1;
-    to: Chord$1;
-};
-/**
- * Find cadences between consecutive segments of a chord timeline.
- *
- * Each adjacent segment pair is classified with {@link detectCadence}; pairs
- * forming no cadence are skipped.
- *
- * @param timeline The chord timeline to scan.
- * @param key The prevailing key.
- * @returns The cadences found, in time order.
- */
-declare function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceHit[];
-
-/**
- * Arrangement analysis: the capstone that ties the timeline, per-voice analysis,
- * functional harmony, and safety modules together for a whole multi-track piece.
- *
- * A chord timeline and key are inferred once from every track's notes pooled
- * together; each track is then analysed against that shared harmony, notes that
- * clash with the sounding chord are collected as conflicts, and a coarse tension
- * curve is sampled across the piece.
- */
-
-/** The musical role a track plays in the arrangement. */
-type TrackRole = 'melody' | 'harmony' | 'bass' | 'other';
-/** One input track: its notes plus optional name and role. */
-type ArrangementTrack = {
-    name?: string;
-    role?: TrackRole;
-    notes: NoteEvent[];
-};
-/** A track after analysis: its resolved name, role, and per-note annotations. */
-type TrackAnalysis = {
-    name: string;
-    role: TrackRole;
-    /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
-    notes: AnalyzedNote[];
-};
-/** A note that clashes with the harmony sounding beneath it. */
-type Conflict = {
-    beat: number;
-    trackName: string;
-    pitch: number;
-    /** The clash severity: {@link NoteSafety.Warning} or {@link NoteSafety.Dissonant}. */
-    safety: NoteSafety;
-    /** {@link import('../safety/index.js').SafetyResult.reasons} bitmask. */
-    reasons: number;
-    rationale?: string;
-};
-/** The full result of {@link analyzeArrangement}. */
-type ArrangementAnalysis = {
-    key: KeyScale;
-    timeline: ChordTimeline;
-    segmentConfidence: number[];
-    cadences: CadenceHit[];
-    tracks: TrackAnalysis[];
-    /** Notes clashing with the sounding harmony, worst severity first. */
-    conflicts: Conflict[];
-};
-/** Options controlling {@link analyzeArrangement} and {@link tensionCurve}. */
-type ArrangementOptions = {
-    /** Key context; inferred from the pooled notes when omitted. */
-    key?: KeyScale;
-    /** Time signature; defaults to 4/4. */
-    ts?: TimeSignature;
-    /** Chord-slot length in beats; defaults to one bar of `ts`. */
-    harmonicRhythm?: number;
-    /** Safety profile used for conflict detection; defaults to `pop`. */
-    profile?: SafetyProfile;
-};
-/**
- * Analyse a whole arrangement against a single inferred harmony.
- *
- * The chord timeline and key are inferred from the pooled notes of every track
- * (see {@link chordTimelineFromNotes}); pooling all voices is robust even when
- * roles are absent or a track doubles the harmony, so it is preferred over
- * deriving the harmony from a subset. Each track is then labelled note-by-note
- * against that harmony with {@link analyzeVoice}, seeing the other tracks as its
- * accompaniment, and every note is re-checked with {@link evaluateSafety}: those
- * that are not {@link NoteSafety.Safe} against the sounding chord become
- * conflicts, sorted worst severity first and then by beat.
- *
- * @param tracks The tracks to analyse.
- * @param opts Analysis options; see {@link ArrangementOptions}.
- * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
- */
-declare function analyzeArrangement(tracks: ArrangementTrack[], opts?: ArrangementOptions): ArrangementAnalysis;
-/** A tension reading sampled at a beat. */
-type TensionPoint = {
-    beat: number;
-    /** Combined tension in [0, 1]. */
-    tension: number;
-};
-/**
- * Sample the harmonic tension of an arrangement at regular beats.
- *
- * At each sample beat the tension combines three normalized terms:
- *  - the sounding chord's harmonic function (dominant `1`, subdominant `0.5`,
- *    tonic or no chord `0`), weighted {@link FUNCTION_WEIGHT};
- *  - the dissonance of the sounding notes — the larger of the share of sounding
- *    pitches that are not chord tones and the share that {@link evaluateSafety}
- *    rates {@link NoteSafety.Dissonant} — weighted {@link DISSONANCE_WEIGHT};
- *  - the registral span of the sounding notes, saturating at
- *    {@link SPAN_SATURATION} semitones, weighted {@link SPAN_WEIGHT}.
- *
- * The weighted sum is clamped to [0, 1]. The harmony is inferred from all tracks
- * pooled together, so the result is deterministic and self-contained.
- *
- * @param tracks The tracks to sample.
- * @param opts Analysis options plus an optional `step` (default one beat).
- * @returns One {@link TensionPoint} per sampled beat, in beat order.
- * @throws If `step` is not positive.
- */
-declare function tensionCurve(tracks: ArrangementTrack[], opts?: ArrangementOptions & {
-    step?: number;
-}): TensionPoint[];
-
-/**
- * Deterministic bass-line generation over a chord placement.
- *
- * Given a sequence of chord segments and a key, this builds a monophonic bass
- * line in a chosen low register. Several idiomatic styles are supported, from a
- * single held root per segment to a quarter-note walking line that leads by
- * step into each chord change. All pitches are kept in a narrow bass band and
- * consecutive notes move by small intervals; given a seed the output is fully
- * reproducible.
- *
- * Positions and durations are measured in quarter-note beats, matching the
- * library-wide convention.
- */
-
-/** A chord sounding over a half-open beat span `[startBeat, endBeat)`. */
-type BassSegment = {
-    startBeat: number;
-    endBeat: number;
-    chord: Chord$1;
-};
-/** The bass-line idiom to generate. */
-type BassStyle = 'root' | 'rootFifth' | 'pop' | 'walking' | 'arpeggio';
-/** Options controlling {@link generateBassLine}. */
-type BassLineOptions = {
-    /** Chord placement to follow; need not be pre-sorted. */
-    segments: BassSegment[];
-    /** Key/scale context, used for diatonic approach tones in `walking`. */
-    key: KeyScale;
-    /** Time signature; used for metric accents. Default 4/4. */
-    ts?: TimeSignature;
-    /** Bass-line idiom. Default `'root'`. */
-    style?: BassStyle;
-    /** Target register as a base MIDI octave; roots land around `octave*12+12`. Default 2. */
-    octave?: number;
-    /** Seed for the deterministic PRNG. Default 0. */
-    seed?: number;
-};
-/**
- * Generate a bass line following a chord placement.
- *
- * Each segment contributes notes in the chosen bass register per the selected
- * style; consecutive notes are kept within roughly a fifth. Every note's
- * duration extends to the next onset (the final note extends to the last
- * segment's end). Given a seed the output is fully reproducible.
- *
- * @param opts Segments, key, and generation options.
- * @returns Bass notes sorted by onset, non-overlapping.
- */
-declare function generateBassLine(opts: BassLineOptions): NoteEvent[];
-
-/**
- * Test whether every chord pitch class is contained in a scale.
- *
- * @param chordPcs The chord's pitch classes (0..11).
- * @param scaleMask The scale's 12-bit mode mask.
- * @param scaleRootPc The pitch class the mask is rooted on.
- * @returns True if the scale is a superset of the chord.
- */
-declare function scaleMatchesChord(chordPcs: number[], scaleMask: number, scaleRootPc: number): boolean;
-/** A named scale rooted on a pitch class that fits over a chord. */
-type ChordScaleMatch = {
-    name: string;
-    rootPc: number;
-};
-/**
- * List the scales that fit over a chord, best fit first.
- *
- * Only the chord root is considered as the scale root, matching the
- * conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
- * whose pitch-class set is a superset of the chord's is returned, ranked by
- * fewest extra scale tones beyond the chord, then by scale size (heptatonic
- * before larger scales), then by scale name. The chromatic scale is only
- * returned as a fallback when no other scale contains the chord.
- *
- * @param chord The chord to fit scales over.
- * @returns The matching scales rooted on the chord root, best fit first.
- */
-declare function chordScales(chord: Chord$1): ChordScaleMatch[];
-/**
- * List a scale's avoid notes over a chord.
- *
- * An avoid note is a non-chord scale tone that lies a semitone directly above a
- * chord tone; sounding it against the chord clashes. The scale is rooted on the
- * chord root. If the scale does not contain the chord, no avoid notes exist.
- *
- * @param chord The chord providing the chord tones.
- * @param scaleName A key of {@link NAMED_SCALES}.
- * @returns The avoid-note pitch classes, sorted ascending in [0, 11].
- */
-declare function avoidNotes(chord: Chord$1, scaleName: string): number[];
-/**
- * List a scale's available tensions over a chord.
- *
- * Available tensions are scale tones that are neither chord tones nor avoid
- * notes, i.e. the usable color tones (typically the 9/11/13 region). The scale
- * is rooted on the chord root. If the scale does not contain the chord, there
- * are no available tensions.
- *
- * @param chord The chord providing the chord tones.
- * @param scaleName A key of {@link NAMED_SCALES}.
- * @returns The available-tension pitch classes, sorted ascending in [0, 11].
- */
-declare function availableTensions(chord: Chord$1, scaleName: string): number[];
-/** A scale fit over a chord together with its avoid notes and tensions. */
-type ChordScaleReportEntry = {
-    name: string;
-    rootPc: number;
-    avoid: number[];
-    tensions: number[];
-};
-/**
- * Report the best-fitting scales for a chord with their avoid notes and tensions.
- *
- * Combines {@link chordScales}, {@link avoidNotes}, and {@link availableTensions}
- * into a single ergonomic result, ordered best fit first.
- *
- * @param chord The chord to analyze.
- * @param limit Optional maximum number of scales to report; all by default.
- * @returns One entry per reported scale, best fit first.
- */
-declare function chordScaleReport(chord: Chord$1, limit?: number): ChordScaleReportEntry[];
-/** A chord paired with the scale chosen for it by {@link scalesForChanges}. */
-type ScaleChoice = {
-    chord: Chord$1;
-    scale: ChordScaleMatch;
-};
-/**
- * Choose one scale per chord across a progression, favoring continuity.
- *
- * Each chord's {@link chordScales} candidates form a stage in a Viterbi-style
- * dynamic program. The transition cost between adjacent choices is the number
- * of pitch classes that differ between their pitch-class sets (the symmetric
- * difference), plus a small penalty for straying from a chord's best-fit scale
- * so that ties break toward the tighter fit. The minimum-total-cost path is
- * returned, one {@link ScaleChoice} per input chord in the original order.
- *
- * @param chords The chord sequence to choose scales for.
- * @returns One scale choice per chord, in input order.
- */
-declare function scalesForChanges(chords: Chord$1[]): ScaleChoice[];
-
-/** Options controlling {@link generateCounterMelody}. */
-type CounterMelodyOptions = {
-    /** The lead line to write against, in ascending onset order. */
-    melody: NoteEvent[];
-    /** Chord sounding at an absolute beat position, or null when none applies. */
-    chordAt: (beat: number) => Chord$1 | null;
-    /** Key/scale context for scale-tone decisions. */
-    key: KeyScale;
-    /** Meter used for strong-beat decisions (default 4/4). */
-    ts?: TimeSignature;
-    /** Which side of the melody the counter line occupies (default `'below'`). */
-    register?: 'above' | 'below';
-    /**
-     * Onset strategy: `'complement'` (default) moves where the melody holds or
-     * rests and reinforces some strong beats; `'follow'` mirrors melody onsets.
-     */
-    rhythm?: 'complement' | 'follow';
-    /** Safety profile applied to candidate pitches (default `'pop'`). */
-    profile?: 'strict' | 'pop';
-    /** Lowest MIDI pitch the counter line may use (default derived from `register`). */
-    pitchLow?: number;
-    /** Highest MIDI pitch the counter line may use (default derived from `register`). */
-    pitchHigh?: number;
-    /** PRNG seed; the same seed always yields the same line (default 0). */
-    seed?: number;
-};
-/**
- * Generate a counter melody against a lead line.
- *
- * Onsets are chosen per `rhythm`: `'follow'` places one counter note on each
- * melody onset; `'complement'` fills melody rests and sustains and reinforces
- * an occasional strong beat, spaced at least a beat apart. Each onset's pitch
- * is picked from the safe pitches in the counter register (chord tones and
- * consonant tensions against the sounding melody note), rejecting candidates
- * that would form a parallel perfect interval with the melody or sit on the
- * wrong side of it, then scored to favour contrary or oblique motion, imperfect
- * consonance, and stepwise movement. Ties break toward the lower pitch, so a
- * given seed always yields the same line. Notes extend to the next counter
- * onset (the last to the melody's end) at a velocity slightly under the melody.
- *
- * @param opts The lead line, chord context callback, key, and generation knobs.
- * @returns The counter line as note events sorted by onset; `[]` for an empty melody.
- */
-declare function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[];
-
-/**
- * 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.
- */
-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.
- */
-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.
- */
-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}).
- */
-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.
- */
-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.
- */
-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.
- */
-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.
- */
-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).
- */
-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.
- */
-declare function isLeadingToneResolution(prev: number, cur: number, key: KeyScale): boolean;
-
-/**
- * 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. */
-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. */
-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).
- */
-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.
- */
-declare function detectChordBest(pitches: number[]): Chord$1 | 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. Returns all 24 keys ranked best-first.
- *
- * @param pitches MIDI pitches or bare pitch classes.
- * @returns Ranked key interpretations.
- */
-declare function detectKey(pitches: number[]): KeyMatch[];
-
-/** A single percussion onset. */
-type DrumHit = {
-    pitch: number;
-    startBeat: number;
-    durationBeat: number;
-    velocity: number;
-};
-
-/** Groove feel controlling off-beat swing. */
-type Feel = 'straight' | 'swing' | 'shuffle';
-/** Public groove style identifiers. */
-type GrooveStyle = 'standard' | 'funk' | 'shuffle' | 'bossa' | 'trap' | 'halftime' | 'breakbeat';
-/** Public role identifiers gating which voices are present. */
-type DrumRole = 'full' | 'ambient' | 'minimal' | 'fxOnly';
-/** Public section identifiers. */
-type PublicSection = 'intro' | 'verse' | 'prechorus' | 'chorus' | 'bridge' | 'outro';
-
-type GrooveFeel = Feel;
-
-/** Public section identifiers for {@link generateDrums}. */
-type Section = PublicSection;
-/** Options controlling {@link generateDrums}. */
-type DrumGenOptions = {
-    bars: number;
-    bpm: number;
-    style: GrooveStyle;
-    section: Section;
-    density: number;
-    fills?: boolean;
-    feel?: GrooveFeel;
-    role?: DrumRole;
-    seed?: number;
-};
-/**
- * Generate a drum performance as a flat list of onsets.
- *
- * Every voice (kick, snare, ghost snares, closed/open/foot hi-hats, ride, toms,
- * crash, and auxiliary percussion) is emitted as a {@link DrumHit} distinguished
- * by its General MIDI pitch. Groove style selects an internal style and feel;
- * `density` sets the backing-density level; `section` shapes kick, hi-hat, ghost,
- * and percussion density. 16th-note hi-hats drop to 8ths at or above 150 BPM.
- * When `fills` is true the final bar is replaced with a fill. Output is fully
- * determined by the options plus `seed`.
- *
- * @param opts Generation options.
- * @returns Percussion onsets in bar order.
- */
-declare function generateDrums(opts: DrumGenOptions): DrumHit[];
-
-/**
- * Groove and humanization: nudging quantized note events toward a more human
- * feel, and capturing/replaying the timing-and-velocity "feel" of a
- * performance as a reusable groove template.
- *
- * Positions and durations are measured in quarter-note beats, matching the
- * library-wide convention. Randomness, where used, always goes through the
- * seeded PRNG from the `random` module so results are fully reproducible.
- */
-
-/** Options controlling {@link humanize}. */
-type HumanizeOptions = {
-    /** Time signature used to derive metric accents. Default 4/4. */
-    ts?: TimeSignature;
-    /** Maximum timing jitter in quarter-note beats, applied as ±this value. Default 0.02. */
-    timing?: number;
-    /** Maximum velocity jitter (MIDI units), applied as ±this value. Default 8. */
-    velocity?: number;
-    /** How much louder strong beats get relative to weak ones, in MIDI velocity units. Default 12. */
-    accent?: number;
-    /** Velocity assumed for events with no `velocity` of their own. Default 80. */
-    baseVelocity?: number;
-    /** Seed for the deterministic PRNG. Default 0. */
-    seed?: number;
-};
-/**
- * Humanize a sequence of note events by nudging their timing and velocity
- * with small, deterministic (seeded) randomness plus a metric-accent shape:
- * events on strong beats (see {@link metricWeight}) come out louder on
- * average than events on weak ones.
- *
- * Each returned event is a copy; `startBeat` is jittered within
- * `[-timing, +timing]` beats and clamped to be non-negative, and `velocity`
- * is the event's own velocity (or `baseVelocity` if it has none) plus an
- * accent term scaled by the event's metric weight plus a jitter within
- * `[-velocity, +velocity]`, clamped to `[1, 127]` and rounded. The metric
- * weight is computed from each event's original (pre-jitter) `startBeat`.
- * `pitch` and `durationBeat` pass through unchanged, and the output keeps the
- * input order.
- *
- * @param events The events to humanize.
- * @param opts Humanization options.
- * @returns Humanized copies of `events`, in input order.
- */
-declare function humanize(events: NoteEvent[], opts?: HumanizeOptions): NoteEvent[];
-/** The recorded feel at a single grid slot: an average timing deviation and velocity. */
-type GrooveSlot = {
-    /** Average `actualStartBeat - quantizedBeat` (in quarter-note beats) for events landing on this slot. */
-    timingOffset: number;
-    /** Average velocity of events landing on this slot; 0 if none did. */
-    velocity: number;
-};
-/** A per-bar grid of timing and velocity deviations captured from a performance. */
-type GrooveTemplate = {
-    /** Grid resolution: equal grid steps per quarter-note beat. */
-    subdivision: number;
-    /** Number of grid slots per bar (`beatsPerBar(ts) * subdivision`). */
-    slotsPerBar: number;
-    /** One entry per grid slot, in slot-index order (slot 0 is the downbeat). */
-    slots: GrooveSlot[];
-};
-/**
- * Extract a groove template from a set of note events: for each grid slot,
- * the average timing deviation from the quantized grid and the average
- * velocity of events landing on it. Slots with no events default to
- * `{ timingOffset: 0, velocity: 0 }`.
- *
- * @param events The (typically "groovy", human-played) events to analyze.
- * @param ts The time signature, used to compute the bar length.
- * @param subdivision Grid resolution: equal grid steps per quarter-note beat.
- * @returns The extracted groove template.
- */
-declare function extractGrooveTemplate(events: NoteEvent[], ts: TimeSignature, subdivision: number): GrooveTemplate;
-/**
- * Apply a groove template to a set of (typically quantized) note events: each
- * event is snapped to its grid slot and then offset by that slot's recorded
- * timing deviation, pushing stiff timing toward the template's feel.
- * Velocity is set to the slot's recorded average when it recorded any
- * (`velocity > 0`); otherwise the event's own velocity is left untouched.
- *
- * @param events The events to reshape.
- * @param template The groove template, from {@link extractGrooveTemplate}.
- * @param ts The time signature, used to compute the bar length.
- * @returns Reshaped copies of `events`, in input order.
- */
-declare function applyGrooveTemplate(events: NoteEvent[], template: GrooveTemplate, ts: TimeSignature): NoteEvent[];
-
-/** Harmonic role a pitch plays within a chord. */
-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.
- */
-type LockLevel = 'identity' | 'quality' | 'voicing';
-/** A pitch's role, lock level, and owning chord. */
-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.
- */
-declare function roleOf(pitch: number, chord: Chord$1, chordId?: number): VoicedRole;
-
-/** A melody note supplied to the harmonizer: a {@link NoteEvent}. */
-type MelodyNote = NoteEvent;
-/** Options controlling {@link harmonizeMelody}. */
-type HarmonizeOptions = {
-    melody: MelodyNote[];
-    key: KeyScale | 'infer';
-    harmonicRhythm: number;
-    reharmonize: 'diatonic' | 'secondaryDominant' | 'borrowed';
-    placement: {
-        transposeSearch: boolean;
-        octaveSearch: boolean;
-    };
-    seed?: number;
-};
-/** The chosen transpose, key, chord path, and per-note roles. */
-type HarmonizeResult = {
-    transposeSemitones: number;
-    key: KeyScale;
-    chords: GeneratedChord[];
-    melodyRoles: {
-        noteIndex: number;
-        role: HarmonyRole;
-    }[];
-};
-/**
- * Harmonize a melody with a min-cost chord progression.
- *
- * The melody is segmented by `harmonicRhythm`; each segment is scored against
- * diatonic (and, per `reharmonize`, secondary-dominant and borrowed) candidate
- * chords by melody fit, and a Viterbi search picks the lowest-cost path using a
- * functional-flow transition cost. When `placement.transposeSearch`/`octaveSearch`
- * is set, the whole melody is transposed across a range and the best
- * `(transpose, progression)` pair is returned; a small tessitura cost breaks
- * ties toward placements that keep the melody in a comfortable register.
- *
- * @param opts Melody, key (or `'infer'`), harmonic rhythm, reharmonization
- *   strength, height-search flags, and seed.
- * @returns The chosen transpose, key, chord path, and per-note roles.
- */
-declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
-
-/** Counterpoint classification of a harmonic interval. */
-declare enum IntervalQuality {
-    PerfectConsonance = 0,
-    ImperfectConsonance = 1,
-    Dissonance = 2
-}
-/**
- * Classify an interval for counterpoint evaluation.
- *
- * The interval is reduced modulo 12, so compound intervals classify as their
- * simple equivalents. The perfect fourth (5) is context-dependent: with
- * `twoVoice` (the default) it classifies as a dissonance, matching
- * {@link isConsonantInterval}; otherwise it is an imperfect consonance.
- *
- * @param semitones Interval size in semitones (may be negative or compound).
- * @param twoVoice When true, the perfect fourth is treated as dissonant.
- * @returns The counterpoint quality of the interval.
- */
-declare function classifyInterval(semitones: number, twoVoice?: boolean): IntervalQuality;
-/**
- * Test whether an interval is a perfect interval (unison/octave or fifth).
- *
- * @param semitones Interval size in semitones (may be negative or compound).
- * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.
- */
-declare function isPerfectInterval(semitones: number): boolean;
-/**
- * Test whether an interval is consonant.
- *
- * The consonant set is {0, 3, 4, 5, 7, 8, 9} mod 12. In two-voice counterpoint
- * the perfect fourth (5) is treated as a dissonance, so `twoVoice` set to true
- * excludes it.
- *
- * @param semitones Interval size in semitones (may be negative or compound).
- * @param twoVoice When true, the perfect fourth is treated as dissonant.
- * @returns True if the interval is consonant in the given context.
- */
-declare function isConsonantInterval(semitones: number, twoVoice?: boolean): boolean;
-
-/**
- * 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.
- */
-type Note$1 = {
-    letter: number;
-    alter: number;
-    octave?: number;
-};
-/** A spelled interval: a diatonic number, a quality label, and its semitone span. */
-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.
- */
-declare function parseNote(text: string): Note$1;
-/**
- * Render a {@link Note} as scientific pitch notation.
- *
- * @param note The note to format.
- * @returns The note text, including the octave when present.
- */
-declare function formatNote(note: Note$1): string;
-/**
- * Pitch class (0..11) of a note, ignoring octave.
- *
- * @param note The note.
- * @returns The pitch class.
- */
-declare function noteToPitchClass(note: Note$1): 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.
- */
-declare function noteToMidi(note: Note$1): number;
-/**
- * Name a MIDI number as a {@link Note}, choosing sharp or flat spelling.
- *
- * @param midi The MIDI number.
- * @param spelling Whether to prefer sharps or flats for black keys.
- * @returns The spelled note, with octave.
- */
-declare function midiToNote(midi: number, spelling?: 'sharp' | 'flat'): Note$1;
-/**
- * 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.
- */
-declare function spelledInterval(a: Note$1, b: Note$1): SpelledInterval;
-
-/** An inclusive MIDI pitch range for a single voice. */
-type VoiceRange = {
-    min: number;
-    max: number;
-};
-/**
- * Default four-voice SATB ranges, ascending (index 0 = lowest):
- * bass E2–C4 (40–60), tenor C3–G4 (48–67), alto G3–D5 (55–74),
- * soprano C4–G5 (60–79).
- */
-declare const SATB_RANGES: readonly VoiceRange[];
-/** Options controlling {@link voiceChord} and {@link voiceProgression}. */
-type VoicingOptions = {
-    /** Number of voices to realize (default 4). Ignored when `ranges` is given. */
-    voices?: number;
-    /** Explicit per-voice ranges, ascending (index 0 = lowest). Takes precedence over `voices`. */
-    ranges?: VoiceRange[];
-    /** Maximum spacing in semitones between adjacent upper voices (default 12). */
-    maxSpacing?: number;
-};
-/**
- * Total voice-leading cost between two voicings: the sum of absolute semitone
- * motion across voices. 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, or `Infinity` when lengths differ.
- */
-declare function voiceLeadingCost(from: number[], to: number[]): number;
-/**
- * Realize a single chord as one MIDI pitch per voice, ascending (index 0 =
- * lowest). The bass voice takes the chord's `bassPc` when set, otherwise the
- * root; upper voices take chord pitch classes, doubling the root or fifth as
- * needed to fill all voices. The result stays inside each voice's range, keeps
- * adjacent upper voices within `maxSpacing`, avoids voice crossing, and is
- * deterministic: a compact close-position voicing centered in the ranges.
- *
- * @param chord The chord to voice.
- * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
- * @returns MIDI pitches, ascending, one per voice.
- * @throws If no voicing fits the given ranges.
- */
-declare function voiceChord(chord: Chord$1, opts?: VoicingOptions): number[];
-/**
- * Voice a chord progression with smooth voice leading. The first chord is
- * voiced with {@link voiceChord}; each subsequent chord picks, from a bounded
- * deterministic candidate set, the voicing minimizing the voice-leading cost
- * from the previous voicing plus a large penalty per counterpoint violation
- * (parallel perfects/octaves, voice crossing, voice overlap, and over-wide
- * upper-voice spacing).
- *
- * @param chords The chords to voice in order.
- * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
- * @returns One voicing per chord, each ascending with one MIDI pitch per voice.
- * @throws If any chord admits no voicing within the given ranges.
- */
-declare function voiceProgression(chords: Chord$1[], opts?: VoicingOptions): number[][];
-/**
- * A tertian voicing style for {@link voiceChordStyled}.
- *
- * - `close`: the plain close-position tertian stack.
- * - `drop2`: the second voice from the top dropped an octave (drop-2 voicing).
- * - `drop3`: the third voice from the top dropped an octave (drop-3 voicing).
- * - `shell`: root plus guide tones (third and seventh) for seventh chords, or
- *   root/third/fifth for triads; the fifth and tensions are omitted.
- * - `rootless`: the root omitted, keeping third/fifth/seventh and tensions
- *   (a typical left-hand jazz voicing).
- */
-type VoicingStyle = 'close' | 'drop2' | 'drop3' | 'shell' | 'rootless';
-/** Options controlling {@link voiceChordStyled}. */
-type StyledVoicingOptions = {
-    /** Voicing style to build (default `close`). */
-    style?: VoicingStyle;
-    /** Constrain the highest voice to this pitch class (0..11) when given. */
-    topNote?: number;
-    /** Base octave for the close stack; the stack begins near `12 * octave` (default 4). */
-    octave?: number;
-    /** Omit the root regardless of style (relevant for jazz voicings). */
-    rootless?: boolean;
-};
-/**
- * Realize a single chord as an explicit tertian voicing in a chosen style,
- * independent of the SATB range search used by {@link voiceChord}.
- *
- * The chord tones are stacked in close position from the bass (`bassPc`, else
- * `rootPc`) in the given scientific-pitch `octave` upward (octave 4 starts the
- * bass near C4 = MIDI 60, matching {@link midiToNote} and the bass module).
- * When `topNote` is given the stack is rotated so the highest voice's pitch
- * class equals that note (or the nearest chord tone). The chosen
- * {@link VoicingStyle} then transforms the stack, and the result is returned as
- * ascending MIDI pitches (index 0 = lowest).
- *
- * @param chord The chord to voice.
- * @param opts Styled voicing options; defaults to a close voicing at octave 4.
- * @returns MIDI pitches, ascending, one per retained voice.
- */
-declare function voiceChordStyled(chord: Chord$1, opts?: StyledVoicingOptions): 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.
- */
-declare function nextVoicing(current: number[], chord: Chord$1, opts?: VoicingOptions): number[];
-
-/**
- * Fluent, immutable object model over the functional core.
- *
- * Each class wraps one of the library's plain data types (spelled notes,
- * chords, key/scales) and delegates every operation to the existing pure
- * functions. All instances are immutable: fields are read-only, transforming
- * methods return new instances, and getters hand out defensive copies of any
- * mutable data.
- */
-
-/**
- * An immutable spelled note: a diatonic letter plus a chromatic alteration and
- * an optional octave. Wraps the plain note object and delegates to the pitch
- * module; every transformation returns a new instance.
- */
-declare class Note {
-    #private;
-    /**
-     * Wrap a plain note object.
-     *
-     * @param data The spelled note; it is copied, never retained or mutated.
-     */
-    constructor(data: Note$1);
-    /**
-     * Parse scientific pitch notation (e.g. `'C#4'`, `'Bb'`, `'F##3'`).
-     *
-     * @param name The note text.
-     * @returns The parsed note.
-     * @throws If the text is not a valid note.
-     */
-    static of(name: string): Note;
-    /**
-     * Name a MIDI number (middle C = C4 = 60) as a note.
-     *
-     * @param midi The MIDI number.
-     * @param spelling Whether to prefer sharps or flats for black keys.
-     * @returns The spelled note, with octave.
-     */
-    static fromMidi(midi: number, spelling?: 'sharp' | 'flat'): Note;
-    /**
-     * Wrap an existing plain note object.
-     *
-     * @param data The plain note.
-     * @returns The wrapped note.
-     */
-    static fromData(data: Note$1): Note;
-    /** The note rendered as scientific pitch notation, e.g. `'G4'` or `'Bb'`. */
-    get name(): string;
-    /** The pitch class (0..11), ignoring octave. */
-    get pitchClass(): number;
-    /**
-     * The MIDI number (middle C = C4 = 60).
-     *
-     * @throws If the note has no octave and therefore no fixed pitch.
-     */
-    get midi(): number;
-    /** The diatonic letter number: 0..6 for C..B. */
-    get letter(): number;
-    /** The chromatic alteration in semitones: -1 flat, 0 natural, +1 sharp, ... */
-    get alter(): number;
-    /** The octave (scientific pitch notation), or undefined for a bare pitch class. */
-    get octave(): number | undefined;
-    /** A copy of the underlying plain note object. */
-    get data(): Note$1;
-    /**
-     * Transpose by a signed number of semitones.
-     *
-     * When the note carries an octave the transposition happens in MIDI space and
-     * the result is spelled with a sharp preference. An octave-less note stays
-     * octave-less: only its pitch class is moved.
-     *
-     * @param semitones The signed semitone offset.
-     * @returns The transposed note.
-     */
-    transpose(semitones: number): Note;
-    /**
-     * The spelled interval from this note to another.
-     *
-     * @param other The second note.
-     * @returns The diatonic number, quality, and semitone span.
-     */
-    intervalTo(other: Note): SpelledInterval;
-    /**
-     * Whether another note has the same letter, alteration, and octave.
-     *
-     * @param other The note to compare.
-     * @returns True if the spellings are identical.
-     */
-    equals(other: Note): boolean;
-}
-/**
- * An immutable spelled interval value: a diatonic number, a quality label, and
- * a signed semitone span. A thin convenience wrapper over the pitch module's
- * plain interval result.
- */
-declare class Interval {
-    #private;
-    private constructor();
-    /**
-     * The spelled interval between two notes.
-     *
-     * @param a The first note.
-     * @param b The second note.
-     * @returns The interval from `a` to `b`.
-     */
-    static between(a: Note, b: Note): Interval;
-    /**
-     * Build an interval from explicit components.
-     *
-     * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
-     * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
-     * @param semitones Signed semitone span.
-     * @returns The interval.
-     */
-    static of(numberValue: number, quality: string, semitones: number): Interval;
-    /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
-    get number(): number;
-    /** Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`. */
-    get quality(): string;
-    /** Signed semitone span. */
-    get semitones(): number;
-    /** A readable label composed of quality and number, e.g. `'P5'` or `'M3'`. */
-    get name(): string;
-}
-/**
- * An immutable key/scale: a `KeyScale` (root pitch class plus mode mask) paired
- * with a spelled tonic that anchors letter-name spelling. Acts as the factory
- * for key-aware chords.
- */
-declare class Key {
-    #private;
-    /**
-     * Wrap a key/scale and its spelled tonic.
-     *
-     * @param scale The key/scale; its root is normalized to a pitch class.
-     * @param tonic The spelled tonic anchoring letter-name spelling.
-     */
-    constructor(scale: KeyScale, tonic: Note);
-    /**
-     * A major key.
-     *
-     * @param root Tonic as a note name (e.g. `'Eb'`) or a pitch class; numeric
-     *   roots are spelled with a sharp preference.
-     * @returns The major key.
-     */
-    static major(root: string | number): Key;
-    /**
-     * A natural-minor key.
-     *
-     * @param root Tonic as a note name or a pitch class; numeric roots are
-     *   spelled with a flat preference.
-     * @returns The minor key.
-     */
-    static minor(root: string | number): Key;
-    /**
-     * A key on a named scale (e.g. `'dorian'`, `'harmonicMinor'`).
-     *
-     * @param name The scale name, a key of the scale module's named-scale table.
-     * @param root Tonic as a note name or a pitch class.
-     * @returns The key.
-     * @throws If the name is not a known scale.
-     */
-    static named(name: string, root: string | number): Key;
-    /**
-     * Wrap an existing `KeyScale`, synthesizing a spelled tonic when none is
-     * given (flat-preferred for minor-third scales, sharp-preferred otherwise).
-     *
-     * @param scale The key/scale to wrap.
-     * @param tonic Optional spelled tonic.
-     * @returns The key.
-     */
-    static of(scale: KeyScale, tonic?: Note): Key;
-    /** A copy of the underlying plain `KeyScale`. */
-    get scale(): KeyScale;
-    /** The spelled tonic. */
-    get tonic(): Note;
-    /** The tonic pitch class (0..11). */
-    get rootPc(): number;
-    /** Whether the scale has a minor third and no major third. */
-    get isMinor(): boolean;
-    /**
-     * The scale's pitch classes in ascending scale-degree order (degree 0 first).
-     *
-     * @returns One pitch class per scale degree.
-     */
-    pitchClasses(): number[];
-    /**
-     * The spelled scale, one note per degree (e.g. C D E F G A B for C major).
-     *
-     * @returns Spelled octave-less notes in scale-degree order.
-     */
-    notes(): Note[];
-    /**
-     * Alias of {@link Key.notes}.
-     *
-     * @returns Spelled octave-less notes in scale-degree order.
-     */
-    spell(): Note[];
-    /**
-     * The spelled scale as letter-name strings.
-     *
-     * @returns One name per scale degree.
-     */
-    noteNames(): string[];
-    /**
-     * Build a chord on a scale degree, carrying this key as context.
-     *
-     * With an explicit quality the quality's interval template is attached to the
-     * degree's diatonic root; without one the scale-correct diatonic triad is
-     * stacked (e.g. a diminished triad on the leading tone of a major key).
-     *
-     * @param degree 0-based scale degree of the chord root.
-     * @param quality Optional chord quality.
-     * @returns The chord, with this key attached.
-     */
-    chord(degree: number, quality?: ChordQuality): Chord;
-    /**
-     * The diatonic triad on a scale degree, carrying this key as context.
-     *
-     * @param degree 0-based scale degree of the chord root.
-     * @returns The triad, with this key attached.
-     */
-    diatonicTriad(degree: number): Chord;
-    /**
-     * The diatonic seventh chord on a scale degree, carrying this key as context.
-     *
-     * @param degree 0-based scale degree of the chord root.
-     * @returns The seventh chord, with this key attached.
-     */
-    diatonicSeventh(degree: number): Chord;
-    /**
-     * Build the chord denoted by a Roman numeral in this key (including applied
-     * chords such as `'V7/V'`), carrying this key as context.
-     *
-     * @param text The Roman numeral.
-     * @returns The chord, with this key attached.
-     * @throws If the numeral is not valid.
-     */
-    roman(text: string): Chord;
-    /**
-     * Whether a pitch belongs to the scale.
-     *
-     * @param x A MIDI pitch, bare pitch class, or note.
-     * @returns True if the pitch class is a scale tone.
-     */
-    contains(x: number | Note): boolean;
-}
-/**
- * An immutable chord: a root pitch class, quality, interval template, and
- * optional slash bass, optionally carrying a {@link Key} context. Analysis
- * methods (`roman`, `function`, `analyze`, ...) use an explicitly passed key
- * first and fall back to the carried context.
- */
-declare class Chord {
-    #private;
-    /**
-     * Wrap a plain chord object.
-     *
-     * @param data The chord; it is copied, never retained or mutated.
-     * @param key Optional key context for analysis methods.
-     */
-    constructor(data: Chord$1, key?: Key);
-    /**
-     * Build a chord from a root and quality.
-     *
-     * @param root Root as a note name (e.g. `'Eb'`) or a pitch class.
-     * @param quality The chord quality.
-     * @param bass Optional slash-chord bass pitch class.
-     * @returns The chord (without key context).
-     */
-    static of(root: string | number, quality: ChordQuality, bass?: number): Chord;
-    /**
-     * Wrap an existing plain chord object.
-     *
-     * @param data The plain chord.
-     * @returns The wrapped chord (without key context).
-     */
-    static from(data: Chord$1): Chord;
-    /**
-     * Parse a lead-sheet chord symbol (e.g. `'Cmaj7'`, `'F#m7b5'`, `'C/G'`).
-     *
-     * @param symbol The chord symbol.
-     * @returns The chord (without key context).
-     * @throws If the root or quality is not recognized.
-     */
-    static parse(symbol: string): Chord;
-    /**
-     * Identify the chords matching a set of pitches, best interpretation first.
-     *
-     * @param pitches MIDI pitches or bare pitch classes.
-     * @returns Ranked chord interpretations (may be empty).
-     */
-    static detect(pitches: number[]): Chord[];
-    /**
-     * The single best chord interpretation of a pitch set.
-     *
-     * @param pitches MIDI pitches or bare pitch classes.
-     * @returns The top-ranked chord, or null when nothing matches.
-     */
-    static detectBest(pitches: number[]): Chord | null;
-    /** The root pitch class (0..11). */
-    get rootPc(): number;
-    /** The chord quality. */
-    get quality(): ChordQuality;
-    /** A copy of the semitone offsets above the root. */
-    get intervals(): number[];
-    /** The slash-chord bass pitch class, or undefined in root position. */
-    get bassPc(): number | undefined;
-    /** A copy of the underlying plain chord object. */
-    get data(): Chord$1;
-    /** The carried key context, if any. */
-    get key(): Key | undefined;
-    /**
-     * A copy of this chord carrying the given key context.
-     *
-     * @param key The key context to attach.
-     * @returns The new chord.
-     */
-    withKey(key: Key): Chord;
-    /**
-     * The chord's sorted, deduplicated pitch classes.
-     *
-     * @returns Pitch classes ascending in [0, 11].
-     */
-    pitchClasses(): number[];
-    /**
-     * The chord's Roman numeral in a key.
-     *
-     * @param key Key to analyze in; falls back to the carried context.
-     * @returns The Roman numeral string.
-     * @throws If no key is given and none is carried.
-     */
-    roman(key?: Key): string;
-    /**
-     * The chord's harmonic function (tonic / subdominant / dominant) in a key.
-     *
-     * @param key Key to analyze in; falls back to the carried context.
-     * @returns The harmonic function.
-     * @throws If no key is given and none is carried.
-     */
-    function(key?: Key): HarmonicFunction;
-    /**
-     * Full functional analysis: function, borrowing, and Roman numeral.
-     *
-     * @param key Key to analyze in; falls back to the carried context.
-     * @returns The chord analysis.
-     * @throws If no key is given and none is carried.
-     */
-    analyze(key?: Key): ChordAnalysis;
-    /**
-     * Whether the chord is borrowed from the parallel mode (modal interchange).
-     *
-     * @param key Key to analyze in; falls back to the carried context.
-     * @returns True if the chord is borrowed.
-     * @throws If no key is given and none is carried.
-     */
-    isBorrowed(key?: Key): boolean;
-    /**
-     * The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
-     *
-     * @param key Key to analyze in; falls back to the carried context.
-     * @returns The borrowing source, or null.
-     * @throws If no key is given and none is carried.
-     */
-    borrowedSource(key?: Key): BorrowedSource;
-    /**
-     * The chord rendered as a lead-sheet symbol (e.g. `'Cmaj7'`, `'F#m7'`, `'C/G'`).
-     *
-     * @param opts Set `flats: true` to spell the root/bass with flats.
-     * @returns The chord symbol.
-     */
-    symbol(opts?: {
-        flats?: boolean;
-    }): string;
-    /**
-     * Realize the chord as one MIDI pitch per voice, ascending.
-     *
-     * @param opts Voicing options; defaults to four SATB voices.
-     * @returns MIDI pitches, ascending, one per voice.
-     * @throws If no voicing fits the given ranges.
-     */
-    voice(opts?: VoicingOptions): number[];
-    /**
-     * Realize the chord as a single styled voicing (`close`, `drop2`, `drop3`,
-     * `shell`, or `rootless`), optionally constraining the top voice.
-     *
-     * @param opts Styled-voicing options; defaults to a close-position voicing.
-     * @returns MIDI pitches, ascending.
-     */
-    styledVoicing(opts?: StyledVoicingOptions): number[];
-    /**
-     * The negative-harmony mirror of the chord about the key's tonic–dominant
-     * axis (major becomes minor and vice versa).
-     *
-     * @param key Key providing the reflection axis; falls back to the carried
-     *   context.
-     * @returns The mirrored chord, keeping any key context.
-     * @throws If no key is given and none is carried.
-     */
-    negativeHarmony(key?: Key): Chord;
-    /**
-     * The n-th inversion: a copy whose bass is the chord tone `n` steps above the
-     * root in the interval template (`invert(1)` puts the third in the bass).
-     * `n` wraps around the template length; negative values count backwards.
-     *
-     * @param n The inversion number.
-     * @returns The inverted chord, keeping any key context.
-     * @throws If the chord has no intervals.
-     */
-    invert(n: number): Chord;
-    /**
-     * The named scales that fit over this chord, best fit first, rooted on the
-     * chord root.
-     *
-     * @returns The matching scales.
-     */
-    scales(): ChordScaleMatch[];
-    /**
-     * The available tensions (usable non-chord, non-avoid scale tones) of a
-     * scale over this chord.
-     *
-     * @param scaleName A named scale, rooted on the chord root.
-     * @returns Tension pitch classes, ascending in [0, 11].
-     */
-    tensions(scaleName: string): number[];
-    /**
-     * The avoid notes (scale tones a semitone above a chord tone) of a scale
-     * over this chord.
-     *
-     * @param scaleName A named scale, rooted on the chord root.
-     * @returns Avoid-note pitch classes, ascending in [0, 11].
-     */
-    avoidNotes(scaleName: string): number[];
-    /**
-     * Spell the chord tones with letter names, root first, in the key's spelling.
-     *
-     * @param key Key providing the spelled tonic; falls back to the carried
-     *   context.
-     * @returns Spelled octave-less notes in the chord's own (tertian) order.
-     * @throws If no key is given and none is carried.
-     */
-    spell(key?: Key): Note[];
-    /**
-     * Start a progression with this chord followed by others, carrying this
-     * chord's key context (if any).
-     *
-     * @param others The chords following this one.
-     * @returns The progression.
-     */
-    progressionTo(...others: Chord[]): Progression;
-    /**
-     * Whether another chord has the same root, quality, intervals, and bass.
-     * Key context is not compared.
-     *
-     * @param other The chord to compare.
-     * @returns True if the chord data is identical.
-     */
-    equals(other: Chord): boolean;
-    /**
-     * The plain chord data, for JSON serialization.
-     *
-     * @returns A copy of the underlying plain chord object.
-     */
-    toJSON(): Chord$1;
-}
-/**
- * An immutable ordered sequence of chords, optionally carrying a {@link Key}
- * context shared by its analysis methods.
- */
-declare class Progression {
-    #private;
-    /**
-     * Wrap a chord sequence.
-     *
-     * @param chords The chords in order; the array is copied.
-     * @param key Optional key context for analysis methods.
-     */
-    constructor(chords: readonly Chord[], key?: Key);
-    /** A copy of the chord sequence. */
-    get chords(): readonly Chord[];
-    /** The carried key context, if any. */
-    get key(): Key | undefined;
-    /** The number of chords. */
-    get length(): number;
-    /**
-     * A copy of this progression with a chord appended.
-     *
-     * @param chord The chord to append.
-     * @returns The new progression.
-     */
-    add(chord: Chord): Progression;
-    /**
-     * A copy of this progression carrying the given key context.
-     *
-     * @param key The key context to attach.
-     * @returns The new progression.
-     */
-    withKey(key: Key): Progression;
-    /**
-     * Voice the progression with smooth voice leading.
-     *
-     * @param opts Voicing options; defaults to four SATB voices.
-     * @returns One ascending voicing (MIDI pitches) per chord.
-     * @throws If any chord admits no voicing within the given ranges.
-     */
-    voice(opts?: VoicingOptions): number[][];
-    /**
-     * The Roman numeral of each chord in a key.
-     *
-     * @param key Key to analyze in; falls back to the carried context.
-     * @returns One numeral per chord.
-     * @throws If no key is given and none is carried.
-     */
-    roman(key?: Key): string[];
-    /**
-     * The harmonic function of each chord in a key.
-     *
-     * @param key Key to analyze in; falls back to the carried context.
-     * @returns One function per chord.
-     * @throws If no key is given and none is carried.
-     */
-    functions(key?: Key): HarmonicFunction[];
-    /**
-     * Analyze every chord and classify the closing cadence.
-     *
-     * The cadence is detected on the final chord pair and is null when the
-     * progression has fewer than two chords.
-     *
-     * @param key Key to analyze in; falls back to the carried context.
-     * @returns Per-chord analyses and the closing cadence.
-     * @throws If no key is given and none is carried.
-     */
-    analyze(key?: Key): {
-        chords: ChordAnalysis[];
-        cadence: Cadence;
-    };
-}
-
-/** A transformation applicable to a motif cell. */
-type MotifTransform = 'transposeDiatonic' | 'transposeChromatic' | 'invert' | 'retrograde' | 'augment' | 'diminish' | 'sequence';
-/** A single note within a motif cell. */
-type MotifNote = {
-    pitch: number;
-    startBeat: number;
-    durationBeat: number;
-};
-/** A short melodic cell. */
-type MotifCell = {
-    notes: MotifNote[];
-};
-/** Melodic contour shape for {@link generateMotif}. */
-type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
-/** Options controlling {@link generateMotif}. */
-type GenerateMotifOptions = {
-    key: KeyScale;
-    chord?: Chord$1 | null;
-    bars: number;
-    contour?: MotifContour;
-    seed?: number;
-};
-/**
- * Generate a short seed motif over `bars`.
- *
- * The melody follows the requested contour in diatonic steps from the tonic,
- * snapped to the key. When a chord is supplied, notes landing on bar downbeats
- * are pulled to the nearest chord tone. Output is deterministic for a given seed.
- *
- * @param opts Key, optional chord, length, contour, and seed.
- * @returns The generated motif cell.
- */
-declare function generateMotif(opts: GenerateMotifOptions): MotifCell;
-/**
- * Apply a transformation to a motif cell.
- *
- * `invert` reflects pitches about the first note (chromatic, self-inverse);
- * `retrograde` mirrors onsets about the cell span, preserving rests (self-inverse);
- * `augment`/`diminish` scale time by `amount ?? 2` and its reciprocal;
- * `transposeChromatic` adds `amount` semitones; `transposeDiatonic` shifts by
- * `amount` scale degrees when a `key` is given, or — with no `key` — falls back
- * to a chromatic shift of `amount` semitones; `sequence` appends a shifted copy
- * (by `amount` diatonic degrees with a `key`, or by `amount` semitones without
- * one, since it delegates to `transposeDiatonic`).
- *
- * @param cell The cell to transform.
- * @param t The transformation.
- * @param amount Optional parameter (semitones, degrees, or time factor).
- * @param key Key context for the diatonic transforms; without it,
- *   `transposeDiatonic` and `sequence` shift chromatically by semitones.
- * @returns The transformed cell.
- */
-declare function transformMotif(cell: MotifCell, t: MotifTransform, amount?: number, key?: KeyScale): MotifCell;
-/**
- * Lay a motif across `bars` and snap it to a chord timeline.
- *
- * The cell is tiled back-to-back to fill the requested span; each note is then
- * pulled to the nearest chord tone of the segment sounding at its onset, so the
- * developed line spells the underlying harmony.
- *
- * @param cell The source motif.
- * @param timeline Chord segments to snap against.
- * @param key Key context (used to keep snapped pitches sensible).
- * @param bars Number of four-beat bars to fill.
- * @returns The developed, harmony-aware cell.
- */
-declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: KeyScale, bars: number): MotifCell;
-
-/**
- * Deterministic seeded pseudo-random number generation shared across the
- * generative modules (rhythm, drums, bass, groove, counter-melody). A single
- * mulberry32 core exposes the small set of samplers those modules need; given a
- * seed the stream is fully reproducible.
- */
-/** A deterministic PRNG with the sampling helpers the generators need. */
-type Rng = {
-    /** Next float in [0, 1). */
-    next: () => number;
-    /** True with probability `p`. */
-    prob: (p: number) => boolean;
-    /** Integer in the inclusive range [lo, hi]. */
-    range: (lo: number, hi: number) => number;
-    /** Float in [lo, hi). */
-    float: (lo: number, hi: number) => number;
-};
-/**
- * Create a seeded PRNG (mulberry32) exposing the shared samplers.
- *
- * @param seed The 32-bit seed; the same seed always yields the same stream.
- * @returns The seeded generator.
- */
-declare function createRng(seed: number): Rng;
-
-/**
- * Reharmonization: chord substitution, modal-interchange palettes, and negative
- * harmony. These transforms take an existing chord (or a key) and propose
- * alternative harmonies that preserve a chosen relationship — a shared function,
- * a common tone, a tonicizing dominant, or a reflection across the key axis.
- *
- * Roots are pitch classes (0..11); no spelled key signature is required.
- */
-
-/** The kind of substitution relationship a candidate realizes. */
-type SubstitutionType = 'tritone' | 'relative' | 'borrowed' | 'chromatic-mediant' | 'secondary-dominant';
-/** A proposed chord substitution with its relationship, numeral, and function. */
-type Substitution = {
-    chord: Chord$1;
-    type: SubstitutionType;
-    roman: string;
-    function: HarmonicFunction;
-};
-/** Options controlling which substitutions {@link substituteChord} returns. */
-type SubstituteOptions = {
-    /**
-     * Melody pitch classes that must remain chord tones. When given, only
-     * substitutions whose pitch classes contain every listed pitch class are
-     * kept, so the melody stays consonant against the new harmony.
-     */
-    melodyPcs?: number[];
-};
-/**
- * Propose substitutions for a chord within a key.
- *
- * Candidates are generated by several relationships and deduplicated against the
- * original chord and each other:
- *
- * - `tritone`: for a dominant-type chord, the dominant seventh a tritone away.
- * - `secondary-dominant`: for a stable target, the dominant seventh a fifth
- *   above its root (tonicizing it).
- * - `relative`: a diatonic triad a third away that shares two common tones.
- * - `borrowed`: a triad from the parallel mode with the same harmonic function.
- * - `chromatic-mediant`: a major/minor triad a third away sharing one common
- *   tone.
- *
- * Each result carries its Roman numeral and harmonic function in `key`. When
- * `opts.melodyPcs` is given, only substitutions whose pitch classes contain all
- * of those pitch classes are returned.
- *
- * @param chord The chord to reharmonize.
- * @param key The prevailing key.
- * @param opts Optional melody-preservation constraint.
- * @returns The deduplicated substitution candidates.
- */
-declare function substituteChord(chord: Chord$1, key: KeyScale, opts?: SubstituteOptions): Substitution[];
-/** A borrowed chord in the modal-interchange palette of a key. */
-type BorrowedChord = {
-    chord: Chord$1;
-    roman: string;
-    source: BorrowedSource;
-};
-/**
- * The modal-interchange palette of a key.
- *
- * Lists the diatonic triads of the {@link parallelKey} that are not diatonic to
- * `key` (the classic borrowed chords such as `iv`, `bVI`, and `bVII` in a major
- * key), plus the Neapolitan (a major triad on the flat second degree). Each
- * carries its Roman numeral and {@link borrowedSource} relative to `key`.
- *
- * @param key The prevailing key.
- * @returns The borrowed-chord palette.
- */
-declare function modalInterchangePalette(key: KeyScale): BorrowedChord[];
-/**
- * Reflect a chord across the tonic–dominant axis of a key (negative harmony).
- *
- * Every pitch class `p` maps to `(2*T + 7 - p) mod 12`, where `T` is the key
- * tonic — the reflection that swaps the tonic with the dominant. The mirrored
- * pitch classes (including the bass, if set) are reassembled into a chord by
- * {@link detectChordBest}; when no chord is recognized, the mirrored root and
- * the original quality are used as a fallback.
- *
- * @param chord The chord to reflect.
- * @param key The prevailing key.
- * @returns The negative-harmony counterpart of the chord.
- */
-declare function negativeHarmonyMirror(chord: Chord$1, key: KeyScale): Chord$1;
-
-/**
- * Deterministic rhythm generation over a metric grid.
- *
- * Builds a fixed-resolution grid across one or more bars of a time signature
- * and decides, per grid slot, whether it becomes a note onset. Onset
- * probability follows the metric-accent hierarchy from the `meter` module, so
- * strong positions (downbeats, secondary pulses) are favored over weak
- * off-pulse subdivisions. Given a seed the output is fully reproducible.
- *
- * Positions and durations are measured in quarter-note beats, matching the
- * library-wide convention.
- */
-
-/** A single rhythmic note: an onset position and how long it sounds. */
-type RhythmEvent = {
-    /** Onset position in quarter-note beats, absolute from the start of the span. */
-    position: number;
-    /** Duration in quarter-note beats, extending to the next onset. */
-    duration: number;
-};
-/** Options controlling {@link generateRhythm}. */
-type RhythmOptions = {
-    /** Seed for the deterministic PRNG. Default 0. */
-    seed?: number;
-    /** Number of bars to generate. Default 1. */
-    bars?: number;
-    /**
-     * Grid resolution as the number of equal grid steps per quarter-note beat.
-     * The default of 2 yields an eighth-note grid; 4 yields a sixteenth-note
-     * grid, 3 an eighth-note triplet grid, and so on.
-     */
-    subdivision?: number;
-    /**
-     * Overall onset density in [0, 1]. Scales the per-slot onset probability, so
-     * higher values fill more grid slots. Default 0.5.
-     */
-    density?: number;
-};
-/**
- * Map a metric weight (0–3 from {@link metricWeight}) to a base onset
- * probability before density scaling. Strong positions are much more likely to
- * carry an onset than weak ones; the curve is intentionally small and explicit
- * so its behavior is easy to inspect and test.
- *
- * @param weight The metric weight, 0 (off-pulse) to 3 (downbeat).
- * @returns A base onset probability in [0, 1].
- */
-declare function onsetWeightCurve(weight: number): number;
-/**
- * Generate a deterministic rhythmic pattern over `bars` bars of a time
- * signature. A grid is built at the chosen subdivision; each slot becomes an
- * onset with a probability derived from its metric weight scaled by `density`
- * and sampled from the seeded PRNG. The first slot (the downbeat) is always an
- * onset. Each event's duration extends to the next onset, and the last event
- * extends to the end of the span.
- *
- * @param ts The time signature.
- * @param opts Generation options.
- * @returns Onset events sorted by position, non-overlapping, covering the span.
- */
-declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): RhythmEvent[];
-/**
- * Onset density of a generated pattern: the mean number of onsets per bar.
- *
- * @param events Events from {@link generateRhythm}.
- * @param ts The time signature.
- * @returns The onset count divided by the number of bars the events span.
- */
-declare function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number;
-
-/**
- * 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.
- */
-declare function maskFromOffsets(offsets: readonly number[]): number;
-/** Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}. */
-declare const MAJOR_MASK = 2741;
-/** Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}. */
-declare const NATURAL_MINOR_MASK = 1453;
-/** Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}. */
-declare const HARMONIC_MINOR_MASK: number;
-/** Ascending melodic minor: offsets {0,2,3,5,7,9,11}. */
-declare const MELODIC_MINOR_MASK: number;
-/** Dorian mode: offsets {0,2,3,5,7,9,10}. */
-declare const DORIAN_MASK: number;
-/** Phrygian mode: offsets {0,1,3,5,7,8,10}. */
-declare const PHRYGIAN_MASK: number;
-/** Lydian mode: offsets {0,2,4,6,7,9,11}. */
-declare const LYDIAN_MASK: number;
-/** Mixolydian mode: offsets {0,2,4,5,7,9,10}. */
-declare const MIXOLYDIAN_MASK: number;
-/** Locrian mode: offsets {0,1,3,5,6,8,10}. */
-declare const LOCRIAN_MASK: number;
-/** Major pentatonic: offsets {0,2,4,7,9}. */
-declare const MAJOR_PENTATONIC_MASK: number;
-/** Minor pentatonic: offsets {0,3,5,7,10}. */
-declare const MINOR_PENTATONIC_MASK: number;
-/** Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}. */
-declare const BLUES_MASK: number;
-/** Whole-tone scale: offsets {0,2,4,6,8,10}. */
-declare const WHOLE_TONE_MASK: number;
-/** Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}. */
-declare const OCTATONIC_HALF_WHOLE_MASK: number;
-/** Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}. */
-declare const OCTATONIC_WHOLE_HALF_MASK: number;
-/** Chromatic scale: all twelve pitch classes. */
-declare const CHROMATIC_MASK = 4095;
-/** Named scale masks addressable by {@link scaleByName}. */
-declare const NAMED_SCALES: Record<string, number>;
-/** Build a `KeyScale` for a major key on the given root pitch class. */
-declare function majorKey(rootPc: number): KeyScale;
-/** Build a `KeyScale` for a natural-minor key on the given root pitch class. */
-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.
- */
-declare function scaleByName(name: string, rootPc: number): KeyScale;
-/**
- * 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.
- */
-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.
- */
-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.
- */
-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].
- */
-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.
- */
-declare function scaleTonesInDegreeOrder(key: KeyScale): 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).
- */
-declare function spellPitchClass(pc: number, tonic: Note$1, key: KeyScale): Note$1;
-/**
- * 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.
- */
-declare function spellScale(tonic: Note$1, key: KeyScale): Note$1[];
-/**
- * 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.
- */
-declare function spellPitchClasses(pcs: number[], tonic: Note$1, key: KeyScale): Note$1[];
-/**
- * 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.
- */
-declare function spellChord(chord: Chord$1, tonic: Note$1, key: KeyScale): Note$1[];
-/**
- * Convenience: render spelled notes as letter-name strings.
- *
- * @param notes The notes.
- * @returns Their formatted names.
- */
-declare function noteNames(notes: Note$1[]): 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`. The `/` after a quality is ambiguous between a slash bass and the
- * `6/9` quality; it resolves to a bass only when the token following it is
- * itself a valid note.
- *
- * @param text The chord symbol text.
- * @returns The parsed chord.
- * @throws If the root or quality is not recognized.
- */
-declare function parseChordSymbol(text: string): Chord$1;
-/**
- * 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.
- *
- * @param chord The chord to format.
- * @param opts Formatting options.
- * @param opts.flats Prefer flat spellings over sharps for altered roots/basses.
- * @returns The chord symbol text.
- */
-declare function formatChordSymbol(chord: Chord$1, 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.
- */
-declare function transposeChordSymbol(text: string, semitones: number, opts?: {
-    flats?: boolean;
-}): string;
-
-/**
- * Tuning and microtonality: frequency conversion, cents, arbitrary equal
- * temperaments (EDO), and just-intonation ratios.
- *
- * The rest of the library reasons in twelve-tone pitch classes, which is a
- * deliberate scope choice for tonal theory. This module is the escape hatch for
- * anyone who needs actual frequencies, cents, non-12 equal temperaments, or the
- * acoustic (just) tuning behind the tempered intervals.
- */
-/**
- * An equal-tempered tuning: a reference pitch and a number of equal divisions of
- * the octave. With `divisions === 12` a step index is an ordinary MIDI number.
- */
-type Tuning = {
-    /** Step index (MIDI number when `divisions` is 12) whose frequency is `refFreq`. */
-    refStep: number;
-    /** Frequency in Hz of `refStep`. */
-    refFreq: number;
-    /** Equal divisions of the octave (12 standard; e.g. 19 or 31 for microtonal). */
-    divisions: number;
-};
-/** Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz. */
-declare const TWELVE_TET: Tuning;
-/**
- * Build an equal temperament with `n` divisions of the octave.
- *
- * @param n Divisions of the octave (e.g. 19, 24, 31).
- * @param refFreq Reference frequency in Hz (default 440).
- * @param refStep Step index of the reference (default 69).
- * @returns The tuning.
- */
-declare function edo(n: number, refFreq?: number, refStep?: number): Tuning;
-/**
- * Frequency in Hz of a step index under a tuning.
- *
- * @param step Step index (a MIDI number under 12-EDO).
- * @param tuning The tuning (default 12-TET).
- * @returns The frequency in Hz.
- */
-declare function frequencyOf(step: number, tuning?: Tuning): number;
-/**
- * Nearest step index to a frequency under a tuning (the inverse of
- * {@link frequencyOf}, rounded).
- *
- * @param freq Frequency in Hz.
- * @param tuning The tuning (default 12-TET).
- * @returns The nearest step index.
- */
-declare function nearestStep(freq: number, tuning?: Tuning): number;
-/**
- * Interval in cents between two frequencies.
- *
- * @param a Lower/first frequency in Hz.
- * @param b Upper/second frequency in Hz.
- * @returns Cents from `a` to `b` (negative if `b` is lower).
- */
-declare function centsBetweenFreq(a: number, b: number): number;
-/**
- * Cents spanned by a number of equal-temperament steps.
- *
- * @param steps Number of steps.
- * @param tuning The tuning (default 12-TET).
- * @returns The cents.
- */
-declare function centsOfSteps(steps: number, tuning?: Tuning): number;
-/**
- * Cents of a frequency ratio, e.g. `ratioToCents(3, 2)` ≈ 701.955 for the just
- * perfect fifth.
- *
- * @param numerator Ratio numerator.
- * @param denominator Ratio denominator.
- * @returns The interval in cents.
- */
-declare function ratioToCents(numerator: number, denominator: number): number;
-/**
- * Five-limit just-intonation ratios for the twelve interval classes above a
- * unison, indexed by semitone class (0..12).
- */
-declare const JUST_RATIOS: Record<number, [number, number]>;
-/**
- * Cents by which a five-limit just interval departs from its 12-TET tempering
- * (positive means the just interval is wider).
- *
- * @param semitoneClass Semitone class in [0, 12].
- * @returns The deviation in cents, or NaN if the class has no listed ratio.
- */
-declare function justDeviationCents(semitoneClass: number): number;
-
-export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, BLUES_MASK, type BarPosition, type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, type BorrowedSource, CHROMATIC_MASK, type Cadence, type CadenceHit, Chord, type ChordAnalysis, type Chord$1 as ChordData, type ChordMatch, type ChordQuality, type ChordScaleMatch, type ChordScaleReportEntry, type ChordSegment, type ChordTimeline, type ChordTimelineOptions, type ChordTimelineResult, type Conflict, type CounterMelodyOptions, DORIAN_MASK, type DrumGenOptions, type DrumHit, type DrumRole, type GenerateMotifOptions, type GenerateProgressionOptions, type GeneratedChord, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, HARMONIC_MINOR_MASK, type HarmonicFunction, type HarmonizeOptions, type HarmonizeResult, type HarmonyRole, type HumanizeOptions, Interval, IntervalQuality, JUST_RATIOS, Key, type KeyMatch, type KeyScale, LOCRIAN_MASK, LYDIAN_MASK, type LockLevel, MAJOR_MASK, MAJOR_PENTATONIC_MASK, MELODIC_MINOR_MASK, MINOR_PENTATONIC_MASK, MIXOLYDIAN_MASK, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifTransform, NAMED_SCALES, NATURAL_MINOR_MASK, Note, type Note$1 as NoteData, type NoteEvent, NoteSafety, OCTATONIC_HALF_WHOLE_MASK, OCTATONIC_WHOLE_HALF_MASK, PHRYGIAN_MASK, type ProgFunction, type ProgStyle, Progression, type ProgressionPreset, ReasonFlag, type RhythmEvent, type RhythmOptions, type Rng, SATB_RANGES, type SafetyProfile, type SafetyQuery, type SafetyResult, type ScaleChoice, type Section, type SpelledInterval, type StyledVoicingOptions, type SubstituteOptions, type Substitution, type SubstitutionType, TWELVE_TET, type TensionPoint, type TheoryLabel, type TimeSignature, type TrackAnalysis, type TrackRole, type Tuning, type VoiceNote, type VoiceRange, type VoiceSnapshot, type VoicedRole, type VoicingOptions, type VoicingStyle, WHOLE_TONE_MASK, analyzeArrangement, analyzeChord, analyzeVoice, applyGrooveTemplate, availableTensions, avoidNotes, barPositionToBeat, beatToBarPosition, beatsPerBar, borrowedSource, centsBetweenFreq, centsOfSteps, chordFromDegree, chordPitchClasses, chordQualities, chordScaleReport, chordScales, chordTimelineFromChords, chordTimelineFromNotes, chordToRoman, chordToneRole, classifyInterval, createRng, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, detectCadence, detectCadences, detectChord, detectChordBest, detectKey, developMotif, diatonicPitchClasses, diatonicSeventh, diatonicTriad, edo, enumerateSafePitches, evaluateSafety, exceedsSpacing, extractGrooveTemplate, formatChordSymbol, formatNote, formatTimeSignature, frequencyOf, functionOf, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, isBorrowedChord, isCompound, isConsonantInterval, isDiatonic, isForbiddenMelodicLeap, isLeadingToneResolution, isMinorKey, isPerfectInterval, isScaleTone, isStrongBeat, justDeviationCents, majorKey, makeChord, maskFromOffsets, metricWeight, midiToNote, minorKey, modalInterchangePalette, nearestScaleTone, nearestStep, negativeHarmonyMirror, nextVoicing, noteNames, noteToMidi, noteToPitchClass, onsetWeightCurve, parallelKey, parseChordSymbol, parseNote, parseTimeSignature, pitchToScaleDegree, progressions, progressionsByStyle, pulsesPerBar, ratioToCents, rhythmDensity, roleOf, romanToChord, scaleByName, scaleMatchesChord, scaleTonesInDegreeOrder, scalesForChanges, secondaryDominant, spellChord, spellPitchClass, spellPitchClasses, spellScale, spelledInterval, substituteChord, tensionCurve, transformMotif, transposeChordSymbol, tuplet, voiceChord, voiceChordStyled, voiceLeadingCost, voiceProgression };
+export { AnalyzedNote, ArrangementAnalysis, ArrangementOptions, ArrangementTrack, ChordMatch, Conflict, KeyMatch, TensionPoint, TheoryLabel, TrackAnalysis, TrackRole, VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, detectChord, detectChordBest, detectKey, romanToChord, tensionCurve } from './analyze/index.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';
+export { C as CadenceHit, a as ChordSegment, b as ChordTimeline, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from './index-BMPxwjwV.js';
+export { IntervalQuality, JUST_RATIOS, Rng, TWELVE_TET, Tuning, centsBetweenFreq, centsOfSteps, classifyInterval, createRng, edo, frequencyOf, isConsonantInterval, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents } from './core/index.js';
+export { B as BarPosition, T as TimeSignature, b as barPositionToBeat, a as beatToBarPosition, c as beatsPerBar, f as formatTimeSignature, i as isCompound, d as isStrongBeat, m as metricWeight, p as parseTimeSignature, e as pulsesPerBar, t as tuplet } from './index-Cl7mhOFM.js';
+export { N as NoteData, S as SpelledInterval, f as formatNote, m as midiToNote, n as noteToMidi, a as noteToPitchClass, p as parseNote, s as spelledInterval } from './index-CGMZNCx6.js';
+export { K as KeyScale, N as NoteEvent } from './types-MGP29r3t.js';
+export { BassLineOptions, BassSegment, BassStyle, BorrowedChord, CounterMelodyOptions, DrumHit, DrumRole, DrumsOptions, EuclideanKick, GrooveFeel, GrooveSlot, GrooveStyle, GrooveTemplate, HarmonizeOptions, HarmonizeResult, HumanizeOptions, MelodyNote, MotifCell, MotifContour, MotifNote, MotifOptions, MotifTransform, ProgFunction, ProgStyle, ProgressionOptions, ProgressionPreset, RhythmEvent, RhythmOptions, Section, SubstituteOptions, Substitution, SubstitutionType, applyGrooveTemplate, developMotif, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, negativeHarmonyMirror, onsetWeightCurve, progressions, progressionsByStyle, rhythmDensity, substituteChord, transformMotif } from './generate/index.js';
+export { Chord, Interval, Key, Note, Progression } from './model/index.js';
+export { C as ChordData, a as ChordQuality, b as ChordSpan, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from './index-CM5W4rcm.js';
+export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, d as VoicingOptions, 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-D7BAx3S3.js';
+export { BLUES_MASK, CHROMATIC_MASK, 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, 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 } from './theory/index.js';
+export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from './index-CP3wAfEH.js';
+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-BreoJRw0.js';