@libraz/libcantus 0.9.2 → 0.9.4

package/dist/styled-DJbkJQfj.d.cts

@@ -0,0 +1,506 @@
+import { C as Chord } from './index-y_ak9_Hi.cjs';
+import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
+
+declare function maskFromOffsets(offsets: readonly number[]): number;
+/**
+ * Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}.
+ *
+ * @category Scales
+ */
+declare const MAJOR_MASK = 2741;
+/**
+ * Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}.
+ *
+ * @category Scales
+ */
+declare const NATURAL_MINOR_MASK = 1453;
+/**
+ * Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}.
+ *
+ * @category Scales
+ */
+declare const HARMONIC_MINOR_MASK: number;
+/**
+ * Ascending melodic minor: offsets {0,2,3,5,7,9,11}.
+ *
+ * @category Scales
+ */
+declare const MELODIC_MINOR_MASK: number;
+/**
+ * Dorian mode: offsets {0,2,3,5,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const DORIAN_MASK: number;
+/**
+ * Phrygian mode: offsets {0,1,3,5,7,8,10}.
+ *
+ * @category Scales
+ */
+declare const PHRYGIAN_MASK: number;
+/**
+ * Lydian mode: offsets {0,2,4,6,7,9,11}.
+ *
+ * @category Scales
+ */
+declare const LYDIAN_MASK: number;
+/**
+ * Mixolydian mode: offsets {0,2,4,5,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const MIXOLYDIAN_MASK: number;
+/**
+ * Locrian mode: offsets {0,1,3,5,6,8,10}.
+ *
+ * @category Scales
+ */
+declare const LOCRIAN_MASK: number;
+/**
+ * Major pentatonic: offsets {0,2,4,7,9}.
+ *
+ * @category Scales
+ */
+declare const MAJOR_PENTATONIC_MASK: number;
+/**
+ * Minor pentatonic: offsets {0,3,5,7,10}.
+ *
+ * @category Scales
+ */
+declare const MINOR_PENTATONIC_MASK: number;
+/**
+ * Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}.
+ *
+ * @category Scales
+ */
+declare const BLUES_MASK: number;
+/**
+ * Whole-tone scale: offsets {0,2,4,6,8,10}.
+ *
+ * @category Scales
+ */
+declare const WHOLE_TONE_MASK: number;
+/**
+ * Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const OCTATONIC_HALF_WHOLE_MASK: number;
+/**
+ * Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}.
+ *
+ * @category Scales
+ */
+declare const OCTATONIC_WHOLE_HALF_MASK: number;
+/**
+ * Chromatic scale: all twelve pitch classes.
+ *
+ * @category Scales
+ */
+declare const CHROMATIC_MASK = 4095;
+/**
+ * Lydian dominant (melodic minor's fourth mode): offsets {0,2,4,6,7,9,10}.
+ *
+ * The scale over an unaltered dominant with a raised eleventh.
+ *
+ * @category Scales
+ */
+declare const LYDIAN_DOMINANT_MASK: number;
+/**
+ * Mixolydian b13, the aeolian dominant (melodic minor's fifth mode): offsets
+ * {0,2,4,5,7,8,10}.
+ *
+ * The scale over a dominant with a flat thirteenth.
+ *
+ * @category Scales
+ */
+declare const MIXOLYDIAN_B13_MASK: number;
+/**
+ * Locrian natural 2 (melodic minor's sixth mode): offsets {0,2,3,5,6,8,10}.
+ *
+ * The scale over a half-diminished chord used as a minor ii.
+ *
+ * @category Scales
+ */
+declare const LOCRIAN_NATURAL2_MASK: number;
+/**
+ * The altered scale, or superlocrian (melodic minor's seventh mode): offsets
+ * {0,1,3,4,6,8,10}.
+ *
+ * The scale over an altered dominant: every tension raised or lowered.
+ *
+ * @category Scales
+ */
+declare const ALTERED_MASK: number;
+/**
+ * Phrygian dominant (harmonic minor's fifth mode): offsets {0,1,4,5,7,8,10}.
+ *
+ * The scale over the dominant of a minor key, and the characteristic sound of
+ * the flamenco and maqam repertoires.
+ *
+ * @category Scales
+ */
+declare const PHRYGIAN_DOMINANT_MASK: number;
+/**
+ * Named scale masks addressable by {@link scaleByName}.
+ *
+ * @category Scales
+ */
+declare const NAMED_SCALES: Readonly<{
+    major: 2741;
+    ionian: 2741;
+    naturalMinor: 1453;
+    aeolian: 1453;
+    harmonicMinor: number;
+    melodicMinor: number;
+    dorian: number;
+    phrygian: number;
+    lydian: number;
+    mixolydian: number;
+    locrian: number;
+    lydianDominant: number;
+    mixolydianB13: number;
+    locrianNatural2: number;
+    altered: number;
+    phrygianDominant: number;
+    majorPentatonic: number;
+    minorPentatonic: number;
+    blues: number;
+    wholeTone: number;
+    octatonicHalfWhole: number;
+    octatonicWholeHalf: number;
+    chromatic: 4095;
+}>;
+/**
+ * The name of a built-in scale, as accepted by {@link scaleByName},
+ * {@link avoidNotes}, and {@link availableTensions}.
+ *
+ * @category Scales
+ */
+type ScaleName = keyof typeof NAMED_SCALES;
+/**
+ * A scale name that completes to the built-in names but still accepts any
+ * string, so a caller with a name from configuration is not forced to cast.
+ *
+ * @category Scales
+ */
+type ScaleNameInput = ScaleName | (string & {});
+/**
+ * The mask of a named scale, or undefined when the name is not one.
+ *
+ * Looking the name up through this helper is what keeps `'constructor'` or
+ * `'toString'` from resolving to something inherited from `Object.prototype`
+ * and producing a scale whose mask is a function.
+ *
+ * @param name The scale name.
+ * @returns The 12-bit mask, or undefined for an unknown name.
+ * @category Scales
+ */
+declare function namedScaleMask(name: ScaleNameInput): number | undefined;
+/**
+ * The mask of a named scale, rejecting an unknown name.
+ *
+ * Every public entry point that takes a scale name funnels through here, so a
+ * typo is reported the same way everywhere instead of being answered with an
+ * empty result that also means "this scale has none".
+ *
+ * @param name The scale name.
+ * @param label What the name is, for the error message.
+ * @returns The 12-bit mask.
+ * @throws If the name is not a built-in scale.
+ * @category Scales
+ */
+declare function requireScaleMask(name: ScaleNameInput, label?: string): number;
+
+/**
+ * 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.
+ *
+ * @category Scales
+ */
+declare function scaleMatchesChord(chordPcs: number[], scaleMask: number, scaleRootPc: number): boolean;
+/**
+ * A named scale rooted on a pitch class that fits over a chord.
+ *
+ * @category Scales
+ */
+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 once per
+ * distinct pitch-class set (aliased masks such as major/ionian report only the
+ * modal name), ranked by fewest extra scale tones beyond the chord, then by
+ * scale size (heptatonic before larger scales), then by conventional
+ * preference. For bare triads and smaller chords, heptatonic scales rank before
+ * pentatonics and other sizes: a pentatonic adds no modal color over a triad,
+ * so the seven-note modes are the more useful answer. The chromatic scale is
+ * only returned as a fallback when no other scale contains the chord.
+ *
+ * The ranking is by fit, so the first entry is the tightest-fitting scale
+ * rather than the idiomatic choice: a four-note chord that a pentatonic covers
+ * exactly puts that pentatonic ahead of the mode a player would name. Read the
+ * whole list, or pick by name, when the idiomatic scale is what is wanted;
+ * {@link scalesForChanges} makes that choice for a progression.
+ *
+ * @param chord The chord to fit scales over.
+ * @returns The matching scales rooted on the chord root, best fit first.
+ *
+ * @example
+ * ```ts
+ * import { makeChord, chordScales } from '@libraz/libcantus';
+ * const scales = chordScales(makeChord(0, 'maj7'));
+ * // scales for Cmaj7, best fit first; each is { name, rootPc: 0 }
+ * ```
+ *
+ * @category Scales
+ */
+declare function chordScales(chord: Chord): 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].
+ * @throws If `scaleName` is not a built-in scale. An empty result already
+ *   means "this scale has no avoid notes over this chord"; answering a typo
+ *   the same way would make the two indistinguishable.
+ *
+ * @category Scales
+ */
+declare function avoidNotes(chord: Chord, scaleName: ScaleNameInput): 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].
+ * @throws If `scaleName` is not a built-in scale, as {@link avoidNotes} does.
+ *
+ * @example
+ * ```ts
+ * import { makeChord, availableTensions } from '@libraz/libcantus';
+ * availableTensions(makeChord(0, 'maj7'), 'ionian'); // [2, 9] — color tones over Cmaj7
+ * ```
+ *
+ * @category Scales
+ */
+declare function availableTensions(chord: Chord, scaleName: ScaleNameInput): number[];
+/**
+ * A scale fit over a chord together with its avoid notes and tensions.
+ *
+ * @category Scales
+ */
+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.
+ *
+ * @category Scales
+ */
+declare function chordScaleReport(chord: Chord, limit?: number): ChordScaleReportEntry[];
+/**
+ * A chord paired with the scale chosen for it by {@link scalesForChanges}.
+ *
+ * @category Scales
+ */
+type ScaleChoice = {
+    chord: Chord;
+    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.
+ *
+ * @category Scales
+ */
+declare function scalesForChanges(chords: Chord[]): ScaleChoice[];
+
+/**
+ * An inclusive MIDI pitch range for a single voice.
+ *
+ * @category Voicing & Counterpoint
+ */
+type VoiceRange = {
+    readonly min: number;
+    readonly 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).
+ *
+ * @category Voicing & Counterpoint
+ */
+declare const SATB_RANGES: readonly Readonly<VoiceRange>[];
+/**
+ * Options controlling {@link voiceChord} and {@link voiceProgression}.
+ *
+ * @category Voicing & Counterpoint
+ */
+type VoicingOptions = {
+    /**
+     * Number of voices to realize. Ignored when `ranges` is given.
+     *
+     * @defaultValue 4
+     */
+    voices?: number;
+    /** Explicit per-voice ranges, ascending (index 0 = lowest). Takes precedence over `voices`. */
+    ranges?: VoiceRange[];
+    /**
+     * Maximum spacing in semitones between adjacent upper voices.
+     *
+     * @defaultValue 12
+     */
+    maxSpacing?: number;
+    /**
+     * Maximum number of chords {@link voiceProgression} will voice. The search
+     * per chord is bounded internally, so the cost of a progression is linear in
+     * its length; this is the guard against an unbounded caller, not a limit on
+     * the search.
+     *
+     * @defaultValue 1000000
+     */
+    budget?: number;
+    /**
+     * The prevailing key. Supplying it enables the rules that only make sense
+     * relative to a tonic: the leading tone is neither doubled nor left
+     * unresolved. Without it, voicings are chosen from chord structure and
+     * voice-leading distance alone.
+     */
+    key?: KeyScale;
+};
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, voiceChord } from '@libraz/libcantus';
+ * const chord = parseChordSymbol('Cmaj7');
+ * voiceChord(chord); // four ascending MIDI pitches within the SATB ranges
+ * ```
+ * @category Voicing & Counterpoint
+ */
+declare function voiceChord(chord: Chord, opts?: VoicingOptions): number[];
+declare function voiceProgression(chords: readonly Chord[], 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).
+ *
+ * @category Voicing & Counterpoint
+ */
+type VoicingStyle = 'close' | 'drop2' | 'drop3' | 'shell' | 'rootless';
+/**
+ * Options controlling {@link voiceChordStyled}.
+ *
+ * @category Voicing & Counterpoint
+ */
+type StyledVoicingOptions = {
+    /**
+     * Voicing style to build.
+     *
+     * @defaultValue 'close'
+     */
+    style?: VoicingStyle;
+    /** Constrain the highest voice to this pitch class (0..11) when given. */
+    topNote?: number;
+    /**
+     * Base octave in scientific pitch notation: octave 4 starts the stack near
+     * middle C (MIDI 60), i.e. near `12 * (octave + 1)`.
+     *
+     * @defaultValue 4
+     */
+    octave?: number;
+    /**
+     * Omit the root regardless of style (relevant for jazz voicings).
+     *
+     * @defaultValue false
+     */
+    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).
+ *
+ * Every returned pitch is a valid MIDI number: an octave whose stack would run
+ * off either end of the 0..127 range is rejected rather than voiced out of
+ * range, matching {@link nextVoicing}, which clamps its derived ranges.
+ *
+ * @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.
+ * @throws If the voicing would not fit inside MIDI 0..127 at the given octave.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, voiceChordStyled } from '@libraz/libcantus';
+ * const chord = parseChordSymbol('Dm7');
+ * voiceChordStyled(chord, { style: 'drop2' }); // ascending MIDI pitches, drop-2 voicing
+ * ```
+ * @category Voicing & Counterpoint
+ */
+declare function voiceChordStyled(chord: Chord, opts?: StyledVoicingOptions): number[];
+
+export { ALTERED_MASK as A, BLUES_MASK as B, CHROMATIC_MASK as C, DORIAN_MASK as D, scaleMatchesChord as E, scalesForChanges as F, voiceChord as G, HARMONIC_MINOR_MASK as H, voiceChordStyled as I, voiceProgression as J, LOCRIAN_MASK as L, MAJOR_MASK as M, NAMED_SCALES as N, OCTATONIC_HALF_WHOLE_MASK as O, PHRYGIAN_DOMINANT_MASK as P, SATB_RANGES as S, type VoiceRange as V, WHOLE_TONE_MASK as W, type ChordScaleMatch as a, type ChordScaleReportEntry as b, LOCRIAN_NATURAL2_MASK as c, LYDIAN_DOMINANT_MASK as d, LYDIAN_MASK as e, MAJOR_PENTATONIC_MASK as f, MELODIC_MINOR_MASK as g, MINOR_PENTATONIC_MASK as h, MIXOLYDIAN_B13_MASK as i, MIXOLYDIAN_MASK as j, NATURAL_MINOR_MASK as k, OCTATONIC_WHOLE_HALF_MASK as l, PHRYGIAN_MASK as m, type ScaleChoice as n, type ScaleName as o, type ScaleNameInput as p, type StyledVoicingOptions as q, type VoicingOptions as r, type VoicingStyle as s, availableTensions as t, avoidNotes as u, chordScaleReport as v, chordScales as w, maskFromOffsets as x, namedScaleMask as y, requireScaleMask as z };