@libraz/libcantus 0.9.3 → 0.9.5

package/src/theory/scale/degrees.ts

@@ -1,123 +0,0 @@
-import type { KeyScale } from '../../core/types.js';
-
-/** Reduce a pitch (or pitch class) to a pitch class in [0, 11]. */
-function pitchClass(pitch: number): number {
-  return ((Math.trunc(pitch) % 12) + 12) % 12;
-}
-
-/** Scale offset of a pitch relative to the key root, in [0, 11]. */
-function scaleOffset(pitch: number, key: KeyScale): number {
-  return (pitchClass(pitch) - pitchClass(key.rootPc) + 12) % 12;
-}
-
-/**
- * Test whether a pitch belongs to the scale.
- *
- * @param pitch MIDI pitch or bare pitch class.
- * @param key The key/scale to test against.
- * @returns True if the pitch class is a member of the scale.
- *
- * @example
- * ```ts
- * import { majorKey, isScaleTone } from '@libraz/libcantus';
- * const key = majorKey(0); // C major
- * isScaleTone(64, key); // true — E is in C major
- * isScaleTone(61, key); // false — C# is not
- * ```
- *
- * @category Scales
- */
-export function isScaleTone(pitch: number, key: KeyScale): boolean {
-  return ((key.modeMask12 >> scaleOffset(pitch, key)) & 1) === 1;
-}
-
-/**
- * Find the nearest MIDI pitch whose pitch class is in the scale.
- *
- * The search expands symmetrically outward from `pitch`. On a tie (equal
- * distance above and below) the lower pitch is returned.
- *
- * @param pitch MIDI pitch to snap.
- * @param key The key/scale to snap to.
- * @returns The nearest in-scale MIDI pitch.
- *
- * @category Scales
- */
-export function nearestScaleTone(pitch: number, key: KeyScale): number {
-  const base = Math.round(pitch);
-  for (let distance = 0; distance < 12; distance += 1) {
-    const lower = base - distance;
-    if (isScaleTone(lower, key)) {
-      return lower;
-    }
-    const higher = base + distance;
-    if (isScaleTone(higher, key)) {
-      return higher;
-    }
-  }
-  return base;
-}
-
-/**
- * Get the 0-based scale degree of a pitch.
- *
- * @param pitch MIDI pitch or bare pitch class.
- * @param key The key/scale to measure against.
- * @returns The 0-based degree, or -1 if the pitch is not in the scale.
- *
- * @category Scales
- */
-export function pitchToScaleDegree(pitch: number, key: KeyScale): number {
-  const offset = scaleOffset(pitch, key);
-  if (((key.modeMask12 >> offset) & 1) === 0) {
-    return -1;
-  }
-  let degree = 0;
-  for (let n = 0; n < offset; n += 1) {
-    if (((key.modeMask12 >> n) & 1) === 1) {
-      degree += 1;
-    }
-  }
-  return degree;
-}
-
-/**
- * List the pitch classes of a key's scale.
- *
- * @param key The key/scale to enumerate.
- * @returns The member pitch classes, sorted ascending in [0, 11].
- *
- * @category Scales
- */
-export function diatonicPitchClasses(key: KeyScale): number[] {
-  const root = pitchClass(key.rootPc);
-  const pcs: number[] = [];
-  for (let n = 0; n < 12; n += 1) {
-    if (((key.modeMask12 >> n) & 1) === 1) {
-      pcs.push((root + n) % 12);
-    }
-  }
-  return pcs.sort((a, b) => a - b);
-}
-
-/**
- * List the pitch classes of a key's scale in ascending scale-degree order.
- *
- * Degree 0 is the root; degrees follow the mask bits in offset order rather
- * than sorted pitch-class order.
- *
- * @param key The key/scale to enumerate.
- * @returns The member pitch classes ordered by scale degree.
- *
- * @category Scales
- */
-export function scaleTonesInDegreeOrder(key: KeyScale): number[] {
-  const root = pitchClass(key.rootPc);
-  const pcs: number[] = [];
-  for (let n = 0; n < 12; n += 1) {
-    if (((key.modeMask12 >> n) & 1) === 1) {
-      pcs.push((root + n) % 12);
-    }
-  }
-  return pcs;
-}

package/src/theory/scale/index.ts

@@ -1,28 +0,0 @@
-export {
-  diatonicPitchClasses,
-  isScaleTone,
-  nearestScaleTone,
-  pitchToScaleDegree,
-  scaleTonesInDegreeOrder,
-} from './degrees.js';
-export { majorKey, minorKey, scaleByName } from './key.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,
-  maskFromOffsets,
-  NAMED_SCALES,
-  NATURAL_MINOR_MASK,
-  OCTATONIC_HALF_WHOLE_MASK,
-  OCTATONIC_WHOLE_HALF_MASK,
-  PHRYGIAN_MASK,
-  WHOLE_TONE_MASK,
-} from './masks.js';

package/src/theory/scale/key.ts

@@ -1,56 +0,0 @@
-import type { KeyScale } from '../../core/types.js';
-import { MAJOR_MASK, NAMED_SCALES, NATURAL_MINOR_MASK } from './masks.js';
-
-/**
- * Build a `KeyScale` for a major key on the given root pitch class.
- *
- * @example
- * ```ts
- * import { majorKey } from '@libraz/libcantus';
- * const cMajor = majorKey(0); // C major: { rootPc: 0, modeMask12: MAJOR_MASK }
- * ```
- *
- * @category Scales
- */
-export function majorKey(rootPc: number): KeyScale {
-  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: MAJOR_MASK };
-}
-
-/**
- * Build a `KeyScale` for a natural-minor key on the given root pitch class.
- *
- * @example
- * ```ts
- * import { minorKey } from '@libraz/libcantus';
- * const aMinor = minorKey(9); // A natural minor: { rootPc: 9, modeMask12: NATURAL_MINOR_MASK }
- * ```
- *
- * @category Scales
- */
-export function minorKey(rootPc: number): KeyScale {
-  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: NATURAL_MINOR_MASK };
-}
-
-/**
- * Build a `KeyScale` from a named scale (see {@link NAMED_SCALES}).
- *
- * @param name The scale name, e.g. `'dorian'` or `'harmonicMinor'`.
- * @param rootPc The root pitch class.
- * @returns The key/scale.
- * @throws If the name is not a known scale.
- *
- * @example
- * ```ts
- * import { scaleByName } from '@libraz/libcantus';
- * const dDorian = scaleByName('dorian', 2); // D Dorian, rootPc 2
- * ```
- *
- * @category Scales
- */
-export function scaleByName(name: string, rootPc: number): KeyScale {
-  const mask = NAMED_SCALES[name];
-  if (mask === undefined) {
-    throw new Error(`Unknown scale: ${name}`);
-  }
-  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: mask };
-}

package/src/theory/scale/masks.ts

@@ -1,153 +0,0 @@
-/**
- * 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
- */
-export function maskFromOffsets(offsets: readonly number[]): number {
-  let mask = 1;
-  for (const offset of offsets) {
-    mask |= 1 << (((offset % 12) + 12) % 12);
-  }
-  return mask;
-}
-
-/**
- * Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}.
- *
- * @category Scales
- */
-export const MAJOR_MASK = 0b101010110101;
-
-/**
- * Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}.
- *
- * @category Scales
- */
-export const NATURAL_MINOR_MASK = 0b010110101101;
-
-/**
- * Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}.
- *
- * @category Scales
- */
-export const HARMONIC_MINOR_MASK = maskFromOffsets([0, 2, 3, 5, 7, 8, 11]);
-
-/**
- * Ascending melodic minor: offsets {0,2,3,5,7,9,11}.
- *
- * @category Scales
- */
-export const MELODIC_MINOR_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 11]);
-
-/**
- * Dorian mode: offsets {0,2,3,5,7,9,10}.
- *
- * @category Scales
- */
-export const DORIAN_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 10]);
-
-/**
- * Phrygian mode: offsets {0,1,3,5,7,8,10}.
- *
- * @category Scales
- */
-export const PHRYGIAN_MASK = maskFromOffsets([0, 1, 3, 5, 7, 8, 10]);
-
-/**
- * Lydian mode: offsets {0,2,4,6,7,9,11}.
- *
- * @category Scales
- */
-export const LYDIAN_MASK = maskFromOffsets([0, 2, 4, 6, 7, 9, 11]);
-
-/**
- * Mixolydian mode: offsets {0,2,4,5,7,9,10}.
- *
- * @category Scales
- */
-export const MIXOLYDIAN_MASK = maskFromOffsets([0, 2, 4, 5, 7, 9, 10]);
-
-/**
- * Locrian mode: offsets {0,1,3,5,6,8,10}.
- *
- * @category Scales
- */
-export const LOCRIAN_MASK = maskFromOffsets([0, 1, 3, 5, 6, 8, 10]);
-
-/**
- * Major pentatonic: offsets {0,2,4,7,9}.
- *
- * @category Scales
- */
-export const MAJOR_PENTATONIC_MASK = maskFromOffsets([0, 2, 4, 7, 9]);
-
-/**
- * Minor pentatonic: offsets {0,3,5,7,10}.
- *
- * @category Scales
- */
-export const MINOR_PENTATONIC_MASK = maskFromOffsets([0, 3, 5, 7, 10]);
-
-/**
- * Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}.
- *
- * @category Scales
- */
-export const BLUES_MASK = maskFromOffsets([0, 3, 5, 6, 7, 10]);
-
-/**
- * Whole-tone scale: offsets {0,2,4,6,8,10}.
- *
- * @category Scales
- */
-export const WHOLE_TONE_MASK = maskFromOffsets([0, 2, 4, 6, 8, 10]);
-
-/**
- * Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}.
- *
- * @category Scales
- */
-export const OCTATONIC_HALF_WHOLE_MASK = maskFromOffsets([0, 1, 3, 4, 6, 7, 9, 10]);
-
-/**
- * Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}.
- *
- * @category Scales
- */
-export const OCTATONIC_WHOLE_HALF_MASK = maskFromOffsets([0, 2, 3, 5, 6, 8, 9, 11]);
-
-/**
- * Chromatic scale: all twelve pitch classes.
- *
- * @category Scales
- */
-export const CHROMATIC_MASK = 0b111111111111;
-
-/**
- * Named scale masks addressable by {@link scaleByName}.
- *
- * @category Scales
- */
-export const NAMED_SCALES: Record<string, number> = {
-  major: MAJOR_MASK,
-  ionian: MAJOR_MASK,
-  naturalMinor: NATURAL_MINOR_MASK,
-  aeolian: NATURAL_MINOR_MASK,
-  harmonicMinor: HARMONIC_MINOR_MASK,
-  melodicMinor: MELODIC_MINOR_MASK,
-  dorian: DORIAN_MASK,
-  phrygian: PHRYGIAN_MASK,
-  lydian: LYDIAN_MASK,
-  mixolydian: MIXOLYDIAN_MASK,
-  locrian: LOCRIAN_MASK,
-  majorPentatonic: MAJOR_PENTATONIC_MASK,
-  minorPentatonic: MINOR_PENTATONIC_MASK,
-  blues: BLUES_MASK,
-  wholeTone: WHOLE_TONE_MASK,
-  octatonicHalfWhole: OCTATONIC_HALF_WHOLE_MASK,
-  octatonicWholeHalf: OCTATONIC_WHOLE_HALF_MASK,
-  chromatic: CHROMATIC_MASK,
-};

package/src/theory/spelling/index.ts

@@ -1,249 +0,0 @@
-/**
- * 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#.
- */
-
-import type { Note } from '../../core/pitch/index.js';
-import { formatNote } from '../../core/pitch/index.js';
-import type { KeyScale } from '../../core/types.js';
-import type { Chord } from '../chord/index.js';
-import { scaleTonesInDegreeOrder } from '../scale/index.js';
-
-/** Semitone offset of each natural letter above C: C D E F G A B. */
-const LETTER_SEMITONES = [0, 2, 4, 5, 7, 9, 11] as const;
-
-/**
- * Conventional degree assignment for each chromatic offset above the tonic.
- *
- * The letter is derived from the tonic's letter plus `degreeOffset` (so the
- * spelling follows the key's diatonic letters), and the accidental is recomputed
- * for that letter. This covers the flat-side alterations (b2, b3, b6, b7), the
- * raised fourth (#4), and the raised degrees of a minor key: the raised sixth
- * (#6) and the raised leading tone (#7). The latter two keep sharp-side minor
- * keys spelling their raised degrees with the key-correct letter (e.g. F# minor
- * spells its leading tone E#, not F).
- *
- * The `alter` field is illustrative only; `spellPitchClass` recomputes the
- * accidental from the chosen letter.
- */
-const CHROMATIC_SPELLING: Record<number, { degreeOffset: number; alter: number }> = {
-  1: { degreeOffset: 1, alter: -1 }, // b2
-  3: { degreeOffset: 2, alter: -1 }, // b3
-  6: { degreeOffset: 3, alter: 1 }, // #4
-  8: { degreeOffset: 5, alter: -1 }, // b6
-  9: { degreeOffset: 5, alter: 1 }, // #6 (raised sixth of a minor key)
-  10: { degreeOffset: 6, alter: -1 }, // b7
-  11: { degreeOffset: 6, alter: 1 }, // #7 (raised leading tone of a minor key)
-};
-
-function mod12(n: number): number {
-  return ((n % 12) + 12) % 12;
-}
-
-function mod7(n: number): number {
-  return ((n % 7) + 7) % 7;
-}
-
-/** Natural pitch class of a letter (0 = C .. 6 = B). */
-function naturalPc(letter: number): number {
-  return LETTER_SEMITONES[mod7(letter)] ?? 0;
-}
-
-/** Shortest signed alteration (in [-6, 6]) taking a letter's natural pc to `pc`. */
-function alterFor(letter: number, pc: number): number {
-  let d = mod12(pc - naturalPc(letter));
-  if (d > 6) {
-    d -= 12;
-  }
-  return d;
-}
-
-/** Whether the key's scale is a seven-note (heptatonic) scale. */
-function isHeptatonic(key: KeyScale): boolean {
-  return scaleTonesInDegreeOrder(key).length === 7;
-}
-
-/**
- * Spell a single pitch class relative to a spelled tonic and key.
- *
- * Diatonic pitch classes take the scale's letter for their degree; the common
- * chromatic tones (b2, b3, #4, b6, b7) and a minor key's raised degrees (#6, #7)
- * take their conventional, key-correct accidental spelling; anything else falls
- * back to a sharp spelling of the nearest natural.
- *
- * @param pc The pitch class to spell.
- * @param tonic The spelled tonic (its letter anchors the spelling).
- * @param key The key/scale.
- * @returns The spelled note (without octave).
- * @category Pitch & Intervals
- */
-export function spellPitchClass(pc: number, tonic: Note, key: KeyScale): Note {
-  const tonicPc = mod12(naturalPc(tonic.letter) + tonic.alter);
-  const offset = mod12(pc - tonicPc);
-  const tones = scaleTonesInDegreeOrder(key);
-
-  if (isHeptatonic(key)) {
-    const degree = tones.indexOf(mod12(pc));
-    if (degree >= 0) {
-      const letter = mod7(tonic.letter + degree);
-      return { letter, alter: alterFor(letter, pc) };
-    }
-    const chromatic = CHROMATIC_SPELLING[offset];
-    if (chromatic) {
-      const letter = mod7(tonic.letter + chromatic.degreeOffset);
-      return { letter, alter: alterFor(letter, pc) };
-    }
-  }
-
-  // Fallback: name the pitch class from the nearest natural, preferring a sharp.
-  for (let letter = 0; letter < 7; letter += 1) {
-    if (naturalPc(letter) === mod12(pc)) {
-      return { letter, alter: 0 };
-    }
-  }
-  const belowLetter = mod7([0, 0, 1, 1, 2, 3, 3, 4, 4, 5, 5, 6][mod12(pc)] ?? 0);
-  return { letter: belowLetter, alter: alterFor(belowLetter, pc) };
-}
-
-/**
- * Spell every pitch class of a scale, in ascending scale-degree order.
- *
- * Correct for heptatonic scales (each degree gets the next letter). Non-standard
- * scales are spelled tone-by-tone with a sharp preference.
- *
- * @param tonic The spelled tonic.
- * @param key The key/scale.
- * @returns Spelled notes, one per scale degree.
- * @example
- * ```ts
- * import { spellScale, noteNames, parseNote, majorKey } from '@libraz/libcantus';
- * noteNames(spellScale(parseNote('C'), majorKey(0)));
- * // ['C', 'D', 'E', 'F', 'G', 'A', 'B']
- * ```
- * @category Pitch & Intervals
- */
-export function spellScale(tonic: Note, key: KeyScale): Note[] {
-  return scaleTonesInDegreeOrder(key).map((pc) => spellPitchClass(pc, tonic, key));
-}
-
-/**
- * Spell an arbitrary list of pitch classes relative to a key.
- *
- * @param pcs The pitch classes.
- * @param tonic The spelled tonic.
- * @param key The key/scale.
- * @returns Spelled notes, in input order.
- * @category Pitch & Intervals
- */
-export function spellPitchClasses(pcs: number[], tonic: Note, key: KeyScale): Note[] {
-  return pcs.map((pc) => spellPitchClass(pc, tonic, key));
-}
-
-/**
- * Diatonic letter distance implied by a chord interval.
- *
- * Chord intervals are not merely pitch-class distances: 6 is a diminished
- * fifth in the basic chord templates while 18 is an augmented eleventh, and 9
- * is a diminished seventh in `dim7` but a sixth elsewhere. Keeping that
- * distinction is what prevents functional chord tones from being respelled by
- * their nearest key pitch (for example G# becoming Ab in E7).
- */
-function chordLetterOffset(interval: number, chord: Chord): number {
-  switch (interval) {
-    case 0:
-    case 12:
-      return 0;
-    case 1:
-    case 2:
-    case 13:
-    case 14:
-      return 1;
-    case 3:
-    case 4:
-    case 15:
-    case 16:
-      return 2;
-    case 5:
-    case 17:
-    case 18:
-      return 3;
-    case 6:
-    case 7:
-    case 8:
-    case 19:
-      return 4;
-    case 9:
-      return chord.quality === 'dim7' ? 6 : 5;
-    case 20:
-    case 21:
-      return 5;
-    case 10:
-    case 11:
-    case 22:
-    case 23:
-      return 6;
-    default: {
-      // Unknown/custom interval data gets the nearest conventional diatonic
-      // distance. Public builders use the explicit cases above.
-      const octaves = Math.floor(Math.max(0, interval) / 12);
-      const simple = mod12(interval);
-      const simpleOffset = [0, 1, 1, 2, 2, 3, 4, 4, 4, 5, 6, 6][simple] ?? 0;
-      return octaves * 7 + simpleOffset;
-    }
-  }
-}
-
-/**
- * Spell chord tones from an already chosen root spelling.
- *
- * This is exported for the model layer's inversion support; the package
- * barrels intentionally expose the key-aware {@link spellChord} entry point.
- */
-export function spellChordFromRoot(chord: Chord, root: Note): Note[] {
-  return chord.intervals.map((interval) => {
-    const letter = mod7(root.letter + chordLetterOffset(interval, chord));
-    const pc = mod12(chord.rootPc + interval);
-    return { letter, alter: alterFor(letter, pc) };
-  });
-}
-
-/**
- * Spell a chord's tones, in the chord's own (tertian) order, relative to a key.
- *
- * Diatonic chords spell exactly (e.g. G7 in C major -> G B D F). Chromatic chord
- * tones take their conventional spelling; enharmonically ambiguous altered
- * tensions may be spelled by the general convention rather than by chord
- * function.
- *
- * @param chord The chord.
- * @param tonic The spelled tonic of the key.
- * @param key The key/scale.
- * @returns Spelled chord tones, root first.
- * @example
- * ```ts
- * import { spellChord, noteNames, parseNote, majorKey, makeChord } from '@libraz/libcantus';
- * // G7 in C major
- * noteNames(spellChord(makeChord(7, 'dom7'), parseNote('C'), majorKey(0)));
- * // ['G', 'B', 'D', 'F']
- * ```
- * @category Pitch & Intervals
- */
-export function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[] {
-  const root = spellPitchClass(chord.rootPc, tonic, key);
-  return spellChordFromRoot(chord, root);
-}
-
-/**
- * Convenience: render spelled notes as letter-name strings.
- *
- * @param notes The notes.
- * @returns Their formatted names.
- * @category Pitch & Intervals
- */
-export function noteNames(notes: Note[]): string[] {
-  return notes.map(formatNote);
-}