@libraz/libcantus 0.9.4 → 1.0.0

package/dist/masks-DYbE485J.d.cts

@@ -0,0 +1,445 @@
+/**
+ * Build a 12-bit mode mask from a list of semitone offsets above the root.
+ *
+ * Bit 0 (the root) is always set, enforcing the `KeyScale` invariant that the
+ * root is a scale tone even when the offset list omits 0.
+ *
+ * @category Scales
+ */
+declare function maskFromOffsets(offsets: readonly number[]): number;
+/**
+ * Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}.
+ *
+ * @category Scales
+ */
+declare const MAJOR_MASK = 2741;
+/**
+ * Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}.
+ *
+ * @category Scales
+ */
+declare const NATURAL_MINOR_MASK = 1453;
+/**
+ * Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}.
+ *
+ * @category Scales
+ */
+declare const HARMONIC_MINOR_MASK: number;
+/**
+ * Ascending melodic minor: offsets {0,2,3,5,7,9,11}.
+ *
+ * @category Scales
+ */
+declare const MELODIC_MINOR_MASK: number;
+/**
+ * Dorian mode: offsets {0,2,3,5,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const DORIAN_MASK: number;
+/**
+ * Phrygian mode: offsets {0,1,3,5,7,8,10}.
+ *
+ * @category Scales
+ */
+declare const PHRYGIAN_MASK: number;
+/**
+ * Lydian mode: offsets {0,2,4,6,7,9,11}.
+ *
+ * @category Scales
+ */
+declare const LYDIAN_MASK: number;
+/**
+ * Mixolydian mode: offsets {0,2,4,5,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const MIXOLYDIAN_MASK: number;
+/**
+ * Locrian mode: offsets {0,1,3,5,6,8,10}.
+ *
+ * @category Scales
+ */
+declare const LOCRIAN_MASK: number;
+/**
+ * Major pentatonic: offsets {0,2,4,7,9}.
+ *
+ * @category Scales
+ */
+declare const MAJOR_PENTATONIC_MASK: number;
+/**
+ * Minor pentatonic: offsets {0,3,5,7,10}.
+ *
+ * @category Scales
+ */
+declare const MINOR_PENTATONIC_MASK: number;
+/**
+ * Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}.
+ *
+ * @category Scales
+ */
+declare const BLUES_MASK: number;
+/**
+ * Whole-tone scale: offsets {0,2,4,6,8,10}.
+ *
+ * @category Scales
+ */
+declare const WHOLE_TONE_MASK: number;
+/**
+ * Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}.
+ *
+ * @category Scales
+ */
+declare const OCTATONIC_HALF_WHOLE_MASK: number;
+/**
+ * Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}.
+ *
+ * @category Scales
+ */
+declare const OCTATONIC_WHOLE_HALF_MASK: number;
+/**
+ * Chromatic scale: all twelve pitch classes.
+ *
+ * @category Scales
+ */
+declare const CHROMATIC_MASK = 4095;
+/**
+ * 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;
+/**
+ * Miyako-bushi (都節), the hemitonic pentatonic of Japanese urban art music —
+ * shamisen and koto song: offsets {0,1,5,7,8}.
+ *
+ * Two miyako-bushi tetrachords a fourth apart, in the terms of Koizumi's
+ * tetrachord theory: between the two nuclear tones of each tetrachord sits a
+ * note a semitone above the lower one.
+ *
+ * The mask fixes the pitch classes and nothing else: the repertoire's
+ * intonation is not twelve-tone equal temperament, and the scale is a pair of
+ * tetrachords around nuclear tones rather than a ladder of degrees above a
+ * tonic. Cents and non-12 temperaments are the tuning module's business.
+ *
+ * @category Scales
+ */
+declare const MIYAKO_BUSHI_MASK: number;
+/**
+ * Ritsu (律), the anhemitonic pentatonic of Japanese court music and Buddhist
+ * chant: offsets {0,2,5,7,9}.
+ *
+ * Two ritsu tetrachords a fourth apart: the middle note sits a whole tone above
+ * the lower nuclear tone. The result is the same five pitch classes as the
+ * major pentatonic a fourth below, which is why the mask alone cannot say which
+ * tradition is meant.
+ *
+ * @category Scales
+ */
+declare const RITSU_MASK: number;
+/**
+ * Ryūkyū (琉球), the pentatonic of Okinawan music: offsets {0,4,5,7,11}.
+ *
+ * Two ryūkyū tetrachords a fourth apart: the middle note sits a major third
+ * above the lower nuclear tone, which is what puts the two semitone steps under
+ * the fourth and the octave.
+ *
+ * @category Scales
+ */
+declare const RYUKYU_MASK: number;
+/**
+ * The heptatonic set with two augmented seconds: offsets {0,1,4,5,7,8,11}.
+ *
+ * Maqam Hijazkar in Arabic practice, thaat Bhairav in Hindustani practice, and
+ * the double harmonic major scale in English-language scale lists — one
+ * pitch-class set that three traditions arrived at separately and treat
+ * differently.
+ *
+ * @category Scales
+ */
+declare const DOUBLE_HARMONIC_MASK: number;
+/**
+ * Thaat Todi of Hindustani classical music — S r g M' P d N: offsets
+ * {0,1,3,6,7,8,11}.
+ *
+ * @category Scales
+ */
+declare const TODI_MASK: number;
+/**
+ * Thaat Marwa of Hindustani classical music — S r G M' P D N: offsets
+ * {0,1,4,6,7,9,11}.
+ *
+ * The thaat carries the fifth; raga Marwa itself leaves it out, which is the
+ * kind of distinction a pitch-class mask cannot make.
+ *
+ * @category Scales
+ */
+declare const MARWA_MASK: number;
+/**
+ * Thaat Purvi of Hindustani classical music — S r G M' P d N: offsets
+ * {0,1,4,6,7,8,11}.
+ *
+ * @category Scales
+ */
+declare const PURVI_MASK: number;
+/**
+ * Named scale masks addressable by {@link scaleByName}.
+ *
+ * These are the scales of Western common practice and of jazz, the vocabulary
+ * chord-scale theory is stated in. Scales belonging to traditions that chord
+ * function does not organise live in {@link WORLD_SCALES}, which
+ * {@link scaleByName} resolves just as readily; {@link scaleSystemOf} says
+ * which kind a name is.
+ *
+ * @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;
+/**
+ * Scale masks from traditions outside Western common practice, addressable by
+ * {@link scaleByName} exactly as {@link NAMED_SCALES} is.
+ *
+ * They are kept apart from {@link NAMED_SCALES} because chord-scale theory is a
+ * Western practice: a raga offered as the scale over an augmented major seventh
+ * would read as an answer while being a category error. Nothing else separates
+ * them — a `KeyScale` built from one of these masks behaves like any other.
+ *
+ * Three limits are worth stating plainly rather than leaving a caller to
+ * discover:
+ *
+ * - A twelve-bit mask can only hold what twelve-tone equal temperament can
+ *   express. The maqamat that turn on half-flat degrees — Rast, Bayati, Saba,
+ *   Sikah — are therefore absent rather than approximated, and the entries that
+ *   are here are not tuned the way their traditions tune them. Cents, arbitrary
+ *   equal divisions and just ratios live in the tuning module.
+ * - A thaat is the pitch material a raga draws on, not the raga: ascent and
+ *   descent, the notes a phrase leans on, and the ornaments belong to the raga
+ *   and have no place in a mask.
+ * - Several of these sets are the same pitch classes as a Western mode. The
+ *   name is what carries the tradition, so pass the name, not the mask,
+ *   wherever the tradition matters ({@link scaleSystemOf} reads both).
+ *
+ * The second limit is the general case: an entry is the pitch material a
+ * tradition names, never the modal system built on it. A maqam is assembled
+ * from ajnas that are transposed and exchanged as a phrase moves, and Koizumi's
+ * tetrachord theory describes the Japanese scales by the nuclear tones framing
+ * each tetrachord, so `miyakoBushi` and `minyo` differ by tetrachord type — a
+ * difference their pitch classes record without explaining. Reach for these
+ * entries when a pitch set is what is wanted.
+ *
+ * @category Scales
+ */
+declare const WORLD_SCALES: Readonly<{
+    /** Miyako-bushi (都節), the hemitonic pentatonic of Japanese art music. */
+    miyakoBushi: number;
+    /** Ritsu (律), the anhemitonic pentatonic of Japanese court music and chant. */
+    ritsu: number;
+    /**
+     * Min'yō (民謡), the pentatonic of Japanese folk song, called inaka-bushi
+     * (田舎節) opposite miyako-bushi. The same five pitch classes as the minor
+     * pentatonic.
+     */
+    minyo: number;
+    /** Ryūkyū (琉球), the pentatonic of Okinawan music. */
+    ryukyu: number;
+    /** Maqam Ajam of Arabic practice; the same pitch classes as the major scale. */
+    ajam: 2741;
+    /**
+     * Maqam Nahawand of Arabic practice; the same pitch classes as the natural
+     * minor, though practice raises the seventh degree at a cadence.
+     */
+    nahawand: 1453;
+    /** Maqam Kurd of Arabic practice; the same pitch classes as the phrygian mode. */
+    kurd: number;
+    /**
+     * Maqam Hijaz of Arabic practice; the same pitch classes as the phrygian
+     * dominant. Played intonation stretches the augmented second beyond its
+     * tempered size, which is the sound the mask cannot carry.
+     */
+    hijaz: number;
+    /** Maqam Hijazkar of Arabic practice: Hijaz over Hijaz, with two augmented seconds. */
+    hijazkar: number;
+    /** Thaat Bilaval of Hindustani classical music; the same pitch classes as the major scale. */
+    bilaval: 2741;
+    /** Thaat Khamaj; the same pitch classes as the mixolydian mode. */
+    khamaj: number;
+    /** Thaat Kafi; the same pitch classes as the dorian mode. */
+    kafi: number;
+    /** Thaat Asavari; the same pitch classes as the natural minor. */
+    asavari: 1453;
+    /** Thaat Bhairavi; the same pitch classes as the phrygian mode. */
+    bhairavi: number;
+    /** Thaat Bhairav, with komal Re and komal Dha against a natural third and seventh. */
+    bhairav: number;
+    /** Thaat Kalyan; the same pitch classes as the lydian mode. */
+    kalyan: number;
+    /** Thaat Marwa, with komal Re and tivra Ma. */
+    marwa: number;
+    /** Thaat Purvi, Marwa's komal Dha counterpart. */
+    purvi: number;
+    /** Thaat Todi, with komal Re, komal Ga, komal Dha and tivra Ma. */
+    todi: number;
+}>;
+/**
+ * The name of a scale in {@link WORLD_SCALES}.
+ *
+ * @category Scales
+ */
+type WorldScaleName = keyof typeof WORLD_SCALES;
+/**
+ * Alternative names that resolve to a canonical scale name.
+ *
+ * A scale carrying several names gets one canonical entry and its other names
+ * here, so that two spellings of one tradition's scale cannot drift into two
+ * entries with two masks. Transliterations vary, and one pitch-class set is
+ * often named differently in different repertoires.
+ *
+ * @category Scales
+ */
+declare const SCALE_ALIASES: Readonly<{
+    /** Inaka-bushi (田舎節), the name the in/yō pairing gives the min'yō scale. */
+    readonly inakaBushi: "minyo";
+    /** The Okinawan scale, the usual English name for the ryūkyū scale. */
+    readonly okinawan: "ryukyu";
+    /** Turkish spelling of Hijaz. */
+    readonly hicaz: "hijaz";
+    /** The English-language scale-list name for the Hijazkar/Bhairav set. */
+    readonly doubleHarmonic: "hijazkar";
+    /** Transliteration variant of Bilaval. */
+    readonly bilawal: "bilaval";
+    /** Transliteration variant of Marwa. */
+    readonly marva: "marwa";
+    /** Transliteration variant of Purvi. */
+    readonly poorvi: "purvi";
+}>;
+/**
+ * An alternative scale name that {@link resolveScaleName} maps to a canonical one.
+ *
+ * @category Scales
+ */
+type ScaleAliasName = keyof typeof SCALE_ALIASES;
+/**
+ * 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 canonical name a scale name stands for, or undefined when it names no
+ * built-in scale.
+ *
+ * A canonical name resolves to itself; an entry of {@link SCALE_ALIASES}
+ * resolves to the name it is an alias of. The lookup goes through
+ * `Object.hasOwn` for the same reason {@link namedScaleMask} does.
+ *
+ * @param name The scale name or alias.
+ * @returns The canonical name, or undefined for an unknown one.
+ * @example
+ * ```ts
+ * import { resolveScaleName } from '@libraz/libcantus';
+ * resolveScaleName('okinawan'); // 'ryukyu'
+ * resolveScaleName('dorian'); // 'dorian'
+ * ```
+ * @category Scales
+ */
+declare function resolveScaleName(name: ScaleNameInput): ScaleName | WorldScaleName | undefined;
+/**
+ * The mask of a named scale, or undefined when the name is not one.
+ *
+ * Names of {@link NAMED_SCALES}, of {@link WORLD_SCALES} and of
+ * {@link SCALE_ALIASES} all answer here, so a caller never has to know which
+ * register a scale is kept in.
+ *
+ * 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 or alias.
+ * @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;
+
+export { ALTERED_MASK as A, BLUES_MASK as B, CHROMATIC_MASK as C, DORIAN_MASK as D, HARMONIC_MINOR_MASK as H, LOCRIAN_MASK as L, MAJOR_MASK as M, NAMED_SCALES as N, OCTATONIC_HALF_WHOLE_MASK as O, PHRYGIAN_DOMINANT_MASK as P, RITSU_MASK as R, SCALE_ALIASES as S, TODI_MASK as T, WHOLE_TONE_MASK as W, DOUBLE_HARMONIC_MASK as a, LOCRIAN_NATURAL2_MASK as b, LYDIAN_DOMINANT_MASK as c, LYDIAN_MASK as d, MAJOR_PENTATONIC_MASK as e, MARWA_MASK as f, MELODIC_MINOR_MASK as g, MINOR_PENTATONIC_MASK as h, MIXOLYDIAN_B13_MASK as i, MIXOLYDIAN_MASK as j, MIYAKO_BUSHI_MASK as k, NATURAL_MINOR_MASK as l, OCTATONIC_WHOLE_HALF_MASK as m, PHRYGIAN_MASK as n, PURVI_MASK as o, RYUKYU_MASK as p, type ScaleAliasName as q, type ScaleName as r, type ScaleNameInput as s, WORLD_SCALES as t, type WorldScaleName as u, maskFromOffsets as v, namedScaleMask as w, requireScaleMask as x, resolveScaleName as y };