@libraz/libcantus 0.9.3 → 0.9.5

package/src/generate/progression/index.ts

@@ -1,362 +0,0 @@
-import { createRng } from '../../core/random/index.js';
-import type { KeyScale } from '../../core/types.js';
-import { assertGenerationBudget, assertPositiveInt } from '../../core/validation/index.js';
-import type { ChordQuality, ChordSpan } from '../../theory/chord/index.js';
-import { diatonicTriad } from '../../theory/chord/index.js';
-import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
-
-export type { ChordSpan } from '../../theory/chord/index.js';
-
-/**
- * Broad production style a progression preset suits.
- *
- * @category Composition
- */
-export type ProgStyle = 'minimal' | 'dance' | 'idol' | 'rock';
-
-/**
- * Harmonic-function role of a progression as a whole.
- *
- * @category Composition
- */
-export type ProgFunction = 'loop' | 'tensionBuild' | 'cadenceStrong' | 'stable';
-
-/**
- * A named chord-progression preset expressed in scale degrees.
- *
- * @category Composition
- */
-export type ProgressionPreset = {
-  id: string;
-  name: string;
-  degrees: number[];
-  functional: ProgFunction;
-  styles: ProgStyle[];
-};
-
-/**
- * Options controlling {@link generateProgression}.
- *
- * @category Composition
- */
-export type ProgressionOptions = {
-  key: KeyScale;
-  style: ProgStyle;
-  bars: number;
-  presetId?: string;
-  ext?: ChordQuality | 'auto';
-  reharmonize?: boolean;
-  /**
-   * Seed for the deterministic preset choice and reharmonization.
-   *
-   * @defaultValue 0
-   */
-  seed?: number;
-};
-
-const PRESETS: ProgressionPreset[] = [
-  {
-    id: 'fourChordPop',
-    name: 'Four Chord Pop',
-    degrees: [0, 4, 5, 3],
-    functional: 'loop',
-    styles: ['minimal', 'dance', 'idol'],
-  },
-  {
-    id: 'pop1',
-    name: 'Pop 1',
-    degrees: [0, 5, 3, 4],
-    functional: 'loop',
-    styles: ['minimal', 'dance', 'idol'],
-  },
-  {
-    id: 'axis',
-    name: 'Axis',
-    degrees: [5, 3, 0, 4],
-    functional: 'loop',
-    styles: ['minimal', 'dance', 'idol', 'rock'],
-  },
-  {
-    id: 'pop2',
-    name: 'Pop 2',
-    degrees: [3, 0, 4, 5],
-    functional: 'loop',
-    styles: ['minimal', 'dance', 'idol'],
-  },
-  {
-    id: 'classic',
-    name: 'Classic',
-    degrees: [0, 3, 4, 0],
-    functional: 'cadenceStrong',
-    styles: ['dance', 'idol', 'rock'],
-  },
-  {
-    id: 'pop3',
-    name: 'Pop 3',
-    degrees: [0, 3, 5, 4],
-    functional: 'loop',
-    styles: ['minimal', 'dance', 'idol'],
-  },
-  {
-    id: 'royalRoad',
-    name: 'Royal Road',
-    degrees: [3, 4, 2, 5],
-    functional: 'tensionBuild',
-    styles: ['dance', 'idol'],
-  },
-  {
-    id: 'minor1',
-    name: 'Minor 1',
-    degrees: [5, 4, 3, 4],
-    functional: 'tensionBuild',
-    styles: ['idol', 'rock'],
-  },
-  {
-    id: 'minor2',
-    name: 'Minor 2',
-    degrees: [5, 3, 4, 0],
-    functional: 'tensionBuild',
-    styles: ['idol', 'rock'],
-  },
-  {
-    id: 'pop4',
-    name: 'Pop 4',
-    degrees: [0, 4, 2, 3],
-    functional: 'loop',
-    styles: ['minimal', 'dance', 'idol'],
-  },
-  {
-    id: 'pop5',
-    name: 'Pop 5',
-    degrees: [0, 2, 3, 4],
-    functional: 'stable',
-    styles: ['minimal', 'dance', 'idol'],
-  },
-  {
-    id: 'rock1',
-    name: 'Rock 1',
-    degrees: [0, 10, 3, 0],
-    functional: 'tensionBuild',
-    styles: ['rock'],
-  },
-  {
-    id: 'rock2',
-    name: 'Rock 2',
-    degrees: [0, 3, 10, 0],
-    functional: 'tensionBuild',
-    styles: ['rock'],
-  },
-  {
-    id: 'extended4',
-    name: 'Extended 4',
-    degrees: [0, 4, 5, 2],
-    functional: 'stable',
-    styles: ['minimal', 'dance'],
-  },
-  {
-    id: 'minor3',
-    name: 'Minor 3',
-    degrees: [5, 0, 4, 3],
-    functional: 'loop',
-    styles: ['dance', 'idol'],
-  },
-  {
-    id: 'aeolianPop',
-    name: 'Aeolian Pop',
-    degrees: [5, 8, 10, 0],
-    functional: 'tensionBuild',
-    styles: ['minimal', 'dance', 'idol', 'rock'],
-  },
-  {
-    id: 'animeHighEnergy1',
-    name: 'Anime High Energy 1',
-    degrees: [5, 2, 3, 0],
-    functional: 'loop',
-    styles: ['dance', 'idol'],
-  },
-  {
-    id: 'jazzPop',
-    name: 'Jazz Pop',
-    degrees: [1, 4, 0, 5],
-    functional: 'cadenceStrong',
-    styles: ['minimal', 'dance'],
-  },
-  {
-    id: 'animeHighEnergy2',
-    name: 'Anime High Energy 2',
-    degrees: [5, 1, 4, 0],
-    functional: 'cadenceStrong',
-    styles: ['dance', 'idol'],
-  },
-  {
-    id: 'cityPop',
-    name: 'City Pop',
-    degrees: [0, 5, 1, 4],
-    functional: 'stable',
-    styles: ['minimal', 'dance'],
-  },
-  {
-    id: 'extended5',
-    name: 'Extended 5',
-    degrees: [0, 4, 5, 2, 3],
-    functional: 'loop',
-    styles: ['minimal', 'dance', 'idol'],
-  },
-  {
-    id: 'neapolitanPop',
-    name: 'Neapolitan Pop',
-    degrees: [5, 12, 13, 4, 0],
-    functional: 'cadenceStrong',
-    styles: ['minimal', 'dance', 'idol'],
-  },
-];
-
-/** Chromatic semitone offset from the tonic for borrowed (non-diatonic) degrees. */
-const BORROWED_OFFSET: Record<number, number> = {
-  8: 8, // bVI
-  10: 10, // bVII
-  11: 3, // bIII
-  12: 5, // iv
-  13: 1, // bII
-  14: 6, // #IV
-};
-
-/**
- * All built-in progression presets.
- *
- * @category Composition
- */
-export function progressions(): ProgressionPreset[] {
-  return PRESETS.map((p) => ({ ...p, degrees: [...p.degrees], styles: [...p.styles] }));
-}
-
-/**
- * Presets whose style list includes the given style.
- *
- * @category Composition
- */
-export function progressionsByStyle(style: ProgStyle): ProgressionPreset[] {
-  return progressions().filter((p) => p.styles.includes(style));
-}
-
-/** Root pitch class of a scale degree in the given key, including borrowed degrees. */
-function degreeToRootPc(degree: number, key: KeyScale): number {
-  if (degree >= 0 && degree <= 6) {
-    const tones = scaleTonesInDegreeOrder(key);
-    return tones.length > 0 ? (tones[degree % tones.length] ?? key.rootPc % 12) : key.rootPc % 12;
-  }
-  const offset = BORROWED_OFFSET[degree] ?? 0;
-  return ((((key.rootPc % 12) + offset) % 12) + 12) % 12;
-}
-
-/**
- * Diatonic (or borrowed) triad quality of a degree in the given key.
- *
- * Diatonic degrees (0-6) take their scale-correct triad quality, so non-major
- * keys yield diatonic chords. Borrowed degrees keep their fixed chromatic
- * qualities (`#IV` diminished, `iv` minor, the rest major).
- */
-function autoQuality(degree: number, key: KeyScale): ChordQuality {
-  if (degree >= 0 && degree <= 6) {
-    return diatonicTriad(degree, key).quality;
-  }
-  if (degree === 14) {
-    return 'dim';
-  }
-  if (degree === 12) {
-    return 'min';
-  }
-  return 'maj';
-}
-
-/**
- * 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`. An unknown `presetId` is a
- * caller error and throws rather than silently falling back to a random preset.
- * 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.
- * @throws If `presetId` is given but does not match any built-in preset.
- *
- * @example
- * ```ts
- * import { generateProgression, majorKey } from '@libraz/libcantus';
- * const chords = generateProgression({ key: majorKey(0), style: 'dance', bars: 4 });
- * // Deterministic for a given seed (defaults to 0); one ChordSpan per bar.
- * ```
- *
- * @category Composition
- */
-export function generateProgression(opts: ProgressionOptions): ChordSpan[] {
-  assertPositiveInt(opts.bars, 'progression bars');
-  assertGenerationBudget(opts.bars, 'progression chords');
-  const seed = opts.seed ?? 0;
-  let preset: ProgressionPreset | undefined;
-  if (opts.presetId !== undefined) {
-    preset = PRESETS.find((p) => p.id === opts.presetId);
-    if (preset === undefined) {
-      throw new Error(`Unknown progression preset: ${opts.presetId}`);
-    }
-  }
-  if (preset === undefined) {
-    const pool = PRESETS.filter((p) => p.styles.includes(opts.style));
-    const candidates = pool.length > 0 ? pool : PRESETS;
-    const rng = createRng(seed);
-    const index = Math.floor(rng.next() * candidates.length) % candidates.length;
-    preset = candidates[index] ?? PRESETS[0];
-  }
-  const degrees = preset?.degrees ?? [0];
-  const chords: ChordSpan[] = [];
-  for (let bar = 0; bar < opts.bars; bar += 1) {
-    const degree = degrees[bar % degrees.length] ?? 0;
-    const quality =
-      opts.ext !== undefined && opts.ext !== 'auto' ? opts.ext : autoQuality(degree, opts.key);
-    const chord: ChordSpan = {
-      rootPc: degreeToRootPc(degree, opts.key),
-      quality,
-      startBeat: bar * 4,
-      degree: degree >= 0 && degree <= 6 ? degree : undefined,
-    };
-    chords.push(chord);
-  }
-
-  if (opts.reharmonize) {
-    const tonicPc = (((opts.key.rootPc % 12) + 12) % 12) as number;
-    const rrng = createRng((seed ^ 0x9e3779b9) >>> 0);
-    for (let i = 0; i < chords.length - 1; i += 1) {
-      const cur = chords[i];
-      const next = chords[i + 1];
-      if (!cur || !next) {
-        continue;
-      }
-      const domRoot = (next.rootPc + 7) % 12;
-      const targetsTonic = (next.rootPc - tonicPc + 12) % 12 === 0;
-      const alreadySecondary = cur.rootPc === domRoot && cur.quality === 'dom7';
-      // A secondary dominant inserted at i-1 resolves onto this chord; replacing
-      // it here would orphan that dominant.
-      const isResolutionTarget = chords[i - 1]?.secondaryDominant === true;
-      if (targetsTonic || alreadySecondary || isResolutionTarget) {
-        continue;
-      }
-      if (rrng.next() < 0.5) {
-        chords[i] = {
-          rootPc: domRoot,
-          quality: 'dom7',
-          startBeat: cur.startBeat,
-          secondaryDominant: true,
-        };
-      }
-    }
-  }
-
-  return chords;
-}

package/src/generate/reharmony/index.ts

@@ -1,323 +0,0 @@
-/**
- * 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.
- */
-
-import { detectChordBest } from '../../analyze/detect/index.js';
-import {
-  type BorrowedSource,
-  borrowedSource,
-  chordToRoman,
-  functionOf,
-  type HarmonicFunction,
-  isDiatonic,
-  parallelKey,
-} from '../../analyze/functional/index.js';
-import type { KeyScale } from '../../core/types.js';
-import {
-  type Chord,
-  type ChordQuality,
-  chordPitchClasses,
-  diatonicTriad,
-  makeChord,
-} from '../../theory/chord/index.js';
-import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
-
-/** Reduce a value to a pitch class in [0, 11]. */
-function mod12(n: number): number {
-  return ((n % 12) + 12) % 12;
-}
-
-/**
- * The kind of substitution relationship a candidate realizes.
- *
- * @category Reharmonization
- */
-export type SubstitutionType =
-  | 'tritone'
-  | 'relative'
-  | 'borrowed'
-  | 'chromatic-mediant'
-  | 'secondary-dominant';
-
-/**
- * A proposed chord substitution with its relationship, numeral, and function.
- *
- * @category Reharmonization
- */
-export type Substitution = {
-  chord: Chord;
-  type: SubstitutionType;
-  roman: string;
-  function: HarmonicFunction;
-};
-
-/**
- * Options controlling which substitutions {@link substituteChord} returns.
- *
- * @category Reharmonization
- */
-export 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[];
-};
-
-/** Whether the chord's template carries a given interval (mod 12). */
-function hasInterval(chord: Chord, semitone: number): boolean {
-  return chord.intervals.some((iv) => mod12(iv) === semitone);
-}
-
-/** Whether a chord is a dominant type: a major third with a minor seventh. */
-function isDominantType(chord: Chord): boolean {
-  return hasInterval(chord, 4) && hasInterval(chord, 10);
-}
-
-/**
- * A chord that can be tonicized: it has a perfect fifth and a third but is not
- * itself a dominant seventh (which is an unstable, tonicizing sonority rather
- * than a stable target).
- */
-function isStableTarget(chord: Chord): boolean {
-  const hasFifth = hasInterval(chord, 7);
-  const hasThird = hasInterval(chord, 3) || hasInterval(chord, 4);
-  return hasFifth && hasThird && !isDominantType(chord);
-}
-
-/** Count the pitch classes shared between two pitch-class sets. */
-function commonToneCount(a: number[], b: number[]): number {
-  const set = new Set(b);
-  return a.filter((pc) => set.has(pc)).length;
-}
-
-/** The diatonic triads of a key, one per scale degree. */
-function diatonicTriadsOf(key: KeyScale): Chord[] {
-  const degrees = scaleTonesInDegreeOrder(key).length;
-  const triads: Chord[] = [];
-  for (let degree = 0; degree < degrees; degree += 1) {
-    triads.push(diatonicTriad(degree, key));
-  }
-  return triads;
-}
-
-/** Whether two chords share the same root pitch class and quality. */
-function sameChord(a: Chord, b: Chord): boolean {
-  return mod12(a.rootPc) === mod12(b.rootPc) && a.quality === b.quality;
-}
-
-/** Root offsets (semitones) that form a third above or below a root. */
-const THIRD_OFFSETS = [3, 4, 8, 9] as const;
-
-/**
- * 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.
- * @example
- * ```ts
- * import { substituteChord, makeChord, majorKey } from '@libraz/libcantus';
- * const subs = substituteChord(makeChord(7, 'dom7'), majorKey(0));
- * // includes the tritone sub Db7 (rootPc 1, quality 'dom7')
- * ```
- * @category Reharmonization
- */
-export function substituteChord(
-  chord: Chord,
-  key: KeyScale,
-  opts?: SubstituteOptions,
-): Substitution[] {
-  const original = chordPitchClasses(chord);
-  const candidates: { chord: Chord; type: SubstitutionType }[] = [];
-
-  // Tritone substitution: only for dominant-type chords.
-  if (isDominantType(chord)) {
-    candidates.push({ chord: makeChord(mod12(chord.rootPc + 6), 'dom7'), type: 'tritone' });
-  }
-
-  // Secondary dominant: the V7 tonicizing a stable target.
-  if (isStableTarget(chord)) {
-    candidates.push({
-      chord: makeChord(mod12(chord.rootPc + 7), 'dom7'),
-      type: 'secondary-dominant',
-    });
-  }
-
-  // Relative: a diatonic triad a third away sharing two common tones.
-  for (const triad of diatonicTriadsOf(key)) {
-    const offset = mod12(triad.rootPc - chord.rootPc);
-    if (
-      (THIRD_OFFSETS as readonly number[]).includes(offset) &&
-      commonToneCount(original, chordPitchClasses(triad)) === 2
-    ) {
-      candidates.push({ chord: triad, type: 'relative' });
-    }
-  }
-
-  // Borrowed: a parallel-mode triad sharing the original's harmonic function.
-  const targetFunction = functionOf(chord, key);
-  for (const triad of diatonicTriadsOf(parallelKey(key))) {
-    if (functionOf(triad, key) === targetFunction && !isDiatonic(triad, key)) {
-      candidates.push({ chord: triad, type: 'borrowed' });
-    }
-  }
-
-  // Chromatic mediants: major/minor triads a third away sharing one common tone.
-  for (const offset of THIRD_OFFSETS) {
-    for (const quality of ['maj', 'min'] as const) {
-      const mediant = makeChord(mod12(chord.rootPc + offset), quality);
-      if (
-        commonToneCount(original, chordPitchClasses(mediant)) === 1 &&
-        !isDiatonic(mediant, key)
-      ) {
-        candidates.push({ chord: mediant, type: 'chromatic-mediant' });
-      }
-    }
-  }
-
-  const melodyPcs = opts?.melodyPcs?.map(mod12);
-  const seen = new Set<string>();
-  const results: Substitution[] = [];
-  for (const candidate of candidates) {
-    if (sameChord(candidate.chord, chord)) {
-      continue;
-    }
-    const dedupeKey = `${mod12(candidate.chord.rootPc)}:${candidate.chord.quality}`;
-    if (seen.has(dedupeKey)) {
-      continue;
-    }
-    seen.add(dedupeKey);
-    if (melodyPcs !== undefined) {
-      const pcs = new Set(chordPitchClasses(candidate.chord));
-      if (!melodyPcs.every((pc) => pcs.has(pc))) {
-        continue;
-      }
-    }
-    results.push({
-      chord: candidate.chord,
-      type: candidate.type,
-      roman: chordToRoman(candidate.chord, key),
-      function: functionOf(candidate.chord, key),
-    });
-  }
-  return results;
-}
-
-/**
- * A borrowed chord in the modal-interchange palette of a key.
- *
- * @category Reharmonization
- */
-export type BorrowedChord = {
-  chord: Chord;
-  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.
- * @category Reharmonization
- */
-export function modalInterchangePalette(key: KeyScale): BorrowedChord[] {
-  const palette: BorrowedChord[] = [];
-  const seen = new Set<string>();
-  const add = (chord: Chord) => {
-    const dedupeKey = `${mod12(chord.rootPc)}:${chord.quality}`;
-    if (seen.has(dedupeKey)) {
-      return;
-    }
-    seen.add(dedupeKey);
-    palette.push({
-      chord,
-      roman: chordToRoman(chord, key),
-      source: borrowedSource(chord, key),
-    });
-  };
-
-  for (const triad of diatonicTriadsOf(parallelKey(key))) {
-    if (!isDiatonic(triad, key)) {
-      add(triad);
-    }
-  }
-  // The Neapolitan (major triad on b2) sits outside both parallel modes, so it
-  // is added explicitly — unless b2 is already diatonic (e.g. in a Phrygian key,
-  // where it is a native chord rather than a borrowing).
-  const neapolitan = makeChord(mod12(key.rootPc + 1), 'maj');
-  if (!isDiatonic(neapolitan, key)) {
-    add(neapolitan);
-  }
-  return palette;
-}
-
-/**
- * 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.
- * @example
- * ```ts
- * import { negativeHarmonyMirror, makeChord, majorKey } from '@libraz/libcantus';
- * negativeHarmonyMirror(makeChord(7, 'maj'), majorKey(0));
- * // G major reflected across C's axis => F minor (rootPc 5, quality 'min')
- * ```
- * @category Reharmonization
- */
-export function negativeHarmonyMirror(chord: Chord, key: KeyScale): Chord {
-  const tonic = mod12(key.rootPc);
-  const mirror = (p: number) => mod12(2 * tonic + 7 - p);
-  const pcs = chordPitchClasses(chord).map(mirror);
-  const bassPc = chord.bassPc !== undefined ? mirror(chord.bassPc) : undefined;
-  // Place the mirrored bass an octave below so it is recognized as the lowest
-  // note and preserved through detection.
-  const pitches = bassPc !== undefined ? [bassPc - 12, ...pcs] : pcs;
-  const detected = detectChordBest(pitches);
-  if (detected) {
-    // Without an input bass the mirrored tones are octave-less, so detection may
-    // read the lowest pitch class as a slash bass and report a spurious
-    // inversion. Restore the recognized chord to root position in that case.
-    if (bassPc === undefined && detected.bassPc !== undefined) {
-      return makeChord(detected.rootPc, detected.quality);
-    }
-    return detected;
-  }
-  const quality: ChordQuality = chord.quality;
-  return makeChord(mirror(chord.rootPc), quality, bassPc);
-}