@libraz/libcantus 0.9.3 → 0.9.5

package/dist/chunk-357ZDPVU.cjs

@@ -0,0 +1,162 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+
+
+
+
+var _chunkKQN2ZYNDcjs = require('./chunk-KQN2ZYND.cjs');
+
+
+
+
+
+var _chunkBSLTLGM3cjs = require('./chunk-BSLTLGM3.cjs');
+
+
+var _chunkPI3UXRWKcjs = require('./chunk-PI3UXRWK.cjs');
+
+// src/generate/reharmony/index.ts
+function hasInterval(chord, semitone) {
+  return chord.intervals.some((iv) => _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, iv) === semitone);
+}
+function isDominantType(chord) {
+  return hasInterval(chord, 4) && hasInterval(chord, 10);
+}
+function commonToneCount(a, b) {
+  const set = new Set(b);
+  return a.filter((pc) => set.has(pc)).length;
+}
+function triadQualityOf(chord) {
+  const semis = new Set(chord.intervals.map((interval) => _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, interval)));
+  const hasThird = semis.has(4) ? "maj" : semis.has(3) ? "min" : void 0;
+  if (hasThird === void 0) {
+    return chord.quality;
+  }
+  if (semis.has(6) && !semis.has(7)) {
+    return hasThird === "min" ? "dim" : "majb5";
+  }
+  if (semis.has(8) && !semis.has(7)) {
+    return "aug";
+  }
+  return hasThird;
+}
+function diatonicTriadsOf(key) {
+  const degrees = _chunkBSLTLGM3cjs.scaleTonesInDegreeOrder.call(void 0, key).length;
+  const triads = [];
+  for (let degree = 0; degree < degrees; degree += 1) {
+    triads.push(_chunkBSLTLGM3cjs.diatonicTriad.call(void 0, degree, key));
+  }
+  return triads;
+}
+function sameChord(a, b) {
+  return _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, a.rootPc) === _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, b.rootPc) && a.quality === b.quality;
+}
+var THIRD_OFFSETS = [3, 4, 8, 9];
+function substituteChord(chord, key, opts) {
+  const originalTriad = _chunkBSLTLGM3cjs.chordPitchClasses.call(void 0, _chunkBSLTLGM3cjs.makeChord.call(void 0, chord.rootPc, triadQualityOf(chord)));
+  const candidates = [];
+  if (isDominantType(chord)) {
+    candidates.push({ chord: _chunkBSLTLGM3cjs.makeChord.call(void 0, _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, chord.rootPc + 6), "dom7"), type: "tritone" });
+  }
+  for (const triad of diatonicTriadsOf(key)) {
+    const offset = _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, triad.rootPc - chord.rootPc);
+    if (THIRD_OFFSETS.includes(offset) && commonToneCount(originalTriad, _chunkBSLTLGM3cjs.chordPitchClasses.call(void 0, triad)) === 2) {
+      candidates.push({ chord: triad, type: "relative" });
+    }
+  }
+  const targetFunction = _chunkKQN2ZYNDcjs.functionOf.call(void 0, chord, key);
+  for (const triad of diatonicTriadsOf(_chunkKQN2ZYNDcjs.parallelKey.call(void 0, key))) {
+    if (_chunkKQN2ZYNDcjs.functionOf.call(void 0, triad, key) === targetFunction && !_chunkKQN2ZYNDcjs.isDiatonic.call(void 0, triad, key)) {
+      candidates.push({ chord: triad, type: "borrowed" });
+    }
+  }
+  for (const offset of THIRD_OFFSETS) {
+    for (const quality of ["maj", "min"]) {
+      const mediant = _chunkBSLTLGM3cjs.makeChord.call(void 0, _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, chord.rootPc + offset), quality);
+      if (commonToneCount(originalTriad, _chunkBSLTLGM3cjs.chordPitchClasses.call(void 0, mediant)) === 1 && !_chunkKQN2ZYNDcjs.isDiatonic.call(void 0, mediant, key)) {
+        candidates.push({ chord: mediant, type: "chromaticMediant" });
+      }
+    }
+  }
+  const melodyPcs = _optionalChain([opts, 'optionalAccess', _ => _.melodyPcs, 'optionalAccess', _2 => _2.map, 'call', _3 => _3(_chunkPI3UXRWKcjs.pitchClassOf)]);
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  for (const candidate of candidates) {
+    if (sameChord(candidate.chord, chord)) {
+      continue;
+    }
+    const dedupeKey = `${_chunkPI3UXRWKcjs.pitchClassOf.call(void 0, candidate.chord.rootPc)}:${candidate.chord.quality}`;
+    if (seen.has(dedupeKey)) {
+      continue;
+    }
+    seen.add(dedupeKey);
+    if (melodyPcs !== void 0) {
+      const pcs = new Set(_chunkBSLTLGM3cjs.chordPitchClasses.call(void 0, candidate.chord));
+      if (!melodyPcs.every((pc) => pcs.has(pc))) {
+        continue;
+      }
+    }
+    results.push({
+      chord: candidate.chord,
+      type: candidate.type,
+      // A secondary dominant is named as the applied chord it is, so the
+      // numeral re-parses to the chord that was proposed rather than to a
+      // chromatic chord on the same root.
+      roman: _chunkKQN2ZYNDcjs.chordToRoman.call(void 0, candidate.chord, key, {
+        applied: candidate.type === "secondaryDominant"
+      }),
+      function: _chunkKQN2ZYNDcjs.functionOf.call(void 0, candidate.chord, key)
+    });
+  }
+  return results;
+}
+function modalInterchangePalette(key) {
+  const palette = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (chord) => {
+    const dedupeKey = `${_chunkPI3UXRWKcjs.pitchClassOf.call(void 0, chord.rootPc)}:${chord.quality}`;
+    if (seen.has(dedupeKey)) {
+      return;
+    }
+    seen.add(dedupeKey);
+    palette.push({
+      chord,
+      roman: _chunkKQN2ZYNDcjs.chordToRoman.call(void 0, chord, key),
+      source: _chunkKQN2ZYNDcjs.borrowedSource.call(void 0, chord, key)
+    });
+  };
+  for (const triad of diatonicTriadsOf(_chunkKQN2ZYNDcjs.parallelKey.call(void 0, key))) {
+    if (!_chunkKQN2ZYNDcjs.isDiatonic.call(void 0, triad, key) && _chunkKQN2ZYNDcjs.borrowedSource.call(void 0, triad, key) !== null) {
+      add(triad);
+    }
+  }
+  const neapolitan = _chunkBSLTLGM3cjs.makeChord.call(void 0, _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, key.rootPc + 1), "maj");
+  if (!_chunkKQN2ZYNDcjs.isDiatonic.call(void 0, neapolitan, key)) {
+    add(neapolitan);
+  }
+  return palette;
+}
+function negativeHarmonyMirror(chord, key) {
+  const tonic = _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, key.rootPc);
+  const mirror = (p) => _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, 2 * tonic + 7 - p);
+  const pcs = _chunkBSLTLGM3cjs.chordPitchClasses.call(void 0, chord).map(mirror);
+  const bassPc = chord.bassPc !== void 0 ? mirror(chord.bassPc) : void 0;
+  const pitches = bassPc !== void 0 ? [bassPc - 12, ...pcs] : pcs;
+  const detected = _chunkKQN2ZYNDcjs.detectChordBest.call(void 0, pitches);
+  if (detected) {
+    if (bassPc === void 0 && detected.bassPc !== void 0) {
+      return _chunkBSLTLGM3cjs.makeChord.call(void 0, detected.rootPc, detected.quality);
+    }
+    return detected;
+  }
+  const quality = chord.quality;
+  return _chunkBSLTLGM3cjs.makeChord.call(void 0, mirror(chord.rootPc), quality, bassPc);
+}
+
+
+
+
+
+exports.substituteChord = substituteChord; exports.modalInterchangePalette = modalInterchangePalette; exports.negativeHarmonyMirror = negativeHarmonyMirror;
+//# sourceMappingURL=chunk-357ZDPVU.cjs.map

package/dist/chunk-357ZDPVU.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/libcantus/libcantus/dist/chunk-357ZDPVU.cjs","../src/generate/reharmony/index.ts"],"names":[],"mappings":"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","file":"/home/runner/work/libcantus/libcantus/dist/chunk-357ZDPVU.cjs","sourcesContent":[null,"/**\n * Reharmonization: chord substitution, modal-interchange palettes, and negative\n * harmony. These transforms take an existing chord (or a key) and propose\n * alternative harmonies that preserve a chosen relationship — a shared function,\n * a common tone, a tonicizing dominant, or a reflection across the key axis.\n *\n * Roots are pitch classes (0..11); no spelled key signature is required.\n */\n\nimport { detectChordBest } from '../../analyze/detect/index.js';\nimport {\n  type BorrowedSource,\n  borrowedSource,\n  chordToRoman,\n  functionOf,\n  type HarmonicFunction,\n  isDiatonic,\n  parallelKey,\n} from '../../analyze/functional/index.js';\nimport { pitchClassOf as mod12 } from '../../core/pitch/index.js';\nimport type { KeyScale } from '../../core/types.js';\nimport {\n  type Chord,\n  type ChordQuality,\n  chordPitchClasses,\n  diatonicTriad,\n  makeChord,\n} from '../../theory/chord/index.js';\nimport { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';\n\n/**\n * The kind of substitution relationship a candidate realizes.\n *\n * @category Reharmonization\n */\nexport type SubstitutionType =\n  | 'tritone'\n  | 'relative'\n  | 'borrowed'\n  | 'chromaticMediant'\n  | 'secondaryDominant';\n\n/**\n * A proposed chord substitution with its relationship, numeral, and function.\n *\n * @category Reharmonization\n */\nexport type Substitution = {\n  chord: Chord;\n  type: SubstitutionType;\n  roman: string;\n  function: HarmonicFunction;\n};\n\n/**\n * Options controlling which substitutions {@link substituteChord} returns.\n *\n * @category Reharmonization\n */\nexport type SubstituteOptions = {\n  /**\n   * Melody pitch classes that must remain chord tones. When given, only\n   * substitutions whose pitch classes contain every listed pitch class are\n   * kept, so the melody stays consonant against the new harmony.\n   */\n  melodyPcs?: number[];\n};\n\n/** Whether the chord's template carries a given interval (mod 12). */\nfunction hasInterval(chord: Chord, semitone: number): boolean {\n  return chord.intervals.some((iv) => mod12(iv) === semitone);\n}\n\n/** Whether a chord is a dominant type: a major third with a minor seventh. */\nfunction isDominantType(chord: Chord): boolean {\n  return hasInterval(chord, 4) && hasInterval(chord, 10);\n}\n\n/** Count the pitch classes shared between two pitch-class sets. */\nfunction commonToneCount(a: number[], b: number[]): number {\n  const set = new Set(b);\n  return a.filter((pc) => set.has(pc)).length;\n}\n\n/** The plain triad quality underlying a chord's own quality. */\nfunction triadQualityOf(chord: Chord): ChordQuality {\n  const semis = new Set(chord.intervals.map((interval) => mod12(interval)));\n  const hasThird = semis.has(4) ? 'maj' : semis.has(3) ? 'min' : undefined;\n  if (hasThird === undefined) {\n    return chord.quality; // sus, power, and other non-tertian chords stand alone\n  }\n  if (semis.has(6) && !semis.has(7)) {\n    return hasThird === 'min' ? 'dim' : 'majb5';\n  }\n  if (semis.has(8) && !semis.has(7)) {\n    return 'aug';\n  }\n  return hasThird;\n}\n\n/** The diatonic triads of a key, one per scale degree. */\nfunction diatonicTriadsOf(key: KeyScale): Chord[] {\n  const degrees = scaleTonesInDegreeOrder(key).length;\n  const triads: Chord[] = [];\n  for (let degree = 0; degree < degrees; degree += 1) {\n    triads.push(diatonicTriad(degree, key));\n  }\n  return triads;\n}\n\n/** Whether two chords share the same root pitch class and quality. */\nfunction sameChord(a: Chord, b: Chord): boolean {\n  return mod12(a.rootPc) === mod12(b.rootPc) && a.quality === b.quality;\n}\n\n/** Root offsets (semitones) that form a third above or below a root. */\nconst THIRD_OFFSETS = [3, 4, 8, 9] as const;\n\n/**\n * Propose substitutions for a chord within a key.\n *\n * Candidates are generated by several relationships and deduplicated against the\n * original chord and each other:\n *\n * - `tritone`: for a dominant-type chord, the dominant seventh a tritone away.\n * - `relative`: a diatonic triad a third away that shares two common tones.\n * - `borrowed`: a triad from the parallel mode with the same harmonic function.\n * - `chromaticMediant`: a major/minor triad a third away sharing one common\n *   tone.\n *\n * Each result carries its Roman numeral and harmonic function in `key`. When\n * `opts.melodyPcs` is given, only substitutions whose pitch classes contain all\n * of those pitch classes are returned.\n *\n * @param chord The chord to reharmonize.\n * @param key The prevailing key.\n * @param opts Optional melody-preservation constraint.\n * @returns The deduplicated substitution candidates.\n * @example\n * ```ts\n * import { substituteChord, makeChord, majorKey } from '@libraz/libcantus';\n * const subs = substituteChord(makeChord(7, 'dom7'), majorKey(0));\n * // includes the tritone sub Db7 (rootPc 1, quality 'dom7')\n * ```\n * @category Reharmonization\n */\nexport function substituteChord(\n  chord: Chord,\n  key: KeyScale,\n  opts?: SubstituteOptions,\n): Substitution[] {\n  // The relative test counts common tones against the chord's triad, not its\n  // full pitch-class set: an exact count of two would otherwise be decided by\n  // how many tensions the input carries, so C proposes both Em and Am while\n  // Cmaj7 proposes only Am — penalising the candidate that overlaps *more*.\n  const originalTriad = chordPitchClasses(makeChord(chord.rootPc, triadQualityOf(chord)));\n  const candidates: { chord: Chord; type: SubstitutionType }[] = [];\n\n  // Tritone substitution: only for dominant-type chords.\n  if (isDominantType(chord)) {\n    candidates.push({ chord: makeChord(mod12(chord.rootPc + 6), 'dom7'), type: 'tritone' });\n  }\n\n  // Relative: a diatonic triad a third away sharing two common tones.\n  for (const triad of diatonicTriadsOf(key)) {\n    const offset = mod12(triad.rootPc - chord.rootPc);\n    if (\n      (THIRD_OFFSETS as readonly number[]).includes(offset) &&\n      commonToneCount(originalTriad, chordPitchClasses(triad)) === 2\n    ) {\n      candidates.push({ chord: triad, type: 'relative' });\n    }\n  }\n\n  // Borrowed: a parallel-mode triad sharing the original's harmonic function.\n  const targetFunction = functionOf(chord, key);\n  for (const triad of diatonicTriadsOf(parallelKey(key))) {\n    if (functionOf(triad, key) === targetFunction && !isDiatonic(triad, key)) {\n      candidates.push({ chord: triad, type: 'borrowed' });\n    }\n  }\n\n  // Chromatic mediants: major/minor triads a third away sharing one common tone.\n  for (const offset of THIRD_OFFSETS) {\n    for (const quality of ['maj', 'min'] as const) {\n      const mediant = makeChord(mod12(chord.rootPc + offset), quality);\n      if (\n        commonToneCount(originalTriad, chordPitchClasses(mediant)) === 1 &&\n        !isDiatonic(mediant, key)\n      ) {\n        candidates.push({ chord: mediant, type: 'chromaticMediant' });\n      }\n    }\n  }\n\n  const melodyPcs = opts?.melodyPcs?.map(mod12);\n  const seen = new Set<string>();\n  const results: Substitution[] = [];\n  for (const candidate of candidates) {\n    if (sameChord(candidate.chord, chord)) {\n      continue;\n    }\n    const dedupeKey = `${mod12(candidate.chord.rootPc)}:${candidate.chord.quality}`;\n    if (seen.has(dedupeKey)) {\n      continue;\n    }\n    seen.add(dedupeKey);\n    if (melodyPcs !== undefined) {\n      const pcs = new Set(chordPitchClasses(candidate.chord));\n      if (!melodyPcs.every((pc) => pcs.has(pc))) {\n        continue;\n      }\n    }\n    results.push({\n      chord: candidate.chord,\n      type: candidate.type,\n      // A secondary dominant is named as the applied chord it is, so the\n      // numeral re-parses to the chord that was proposed rather than to a\n      // chromatic chord on the same root.\n      roman: chordToRoman(candidate.chord, key, {\n        applied: candidate.type === 'secondaryDominant',\n      }),\n      function: functionOf(candidate.chord, key),\n    });\n  }\n  return results;\n}\n\n/**\n * A borrowed chord in the modal-interchange palette of a key.\n *\n * @category Reharmonization\n */\nexport type BorrowedChord = {\n  chord: Chord;\n  roman: string;\n  source: BorrowedSource;\n};\n\n/**\n * The modal-interchange palette of a key.\n *\n * Lists the diatonic triads of the {@link parallelKey} that are not diatonic to\n * `key` (the classic borrowed chords such as `iv`, `bVI`, and `bVII` in a major\n * key), plus the Neapolitan (a major triad on the flat second degree). Each\n * carries its Roman numeral and {@link borrowedSource} relative to `key`.\n *\n * @param key The prevailing key.\n * @returns The borrowed-chord palette.\n * @category Reharmonization\n */\nexport function modalInterchangePalette(key: KeyScale): BorrowedChord[] {\n  const palette: BorrowedChord[] = [];\n  const seen = new Set<string>();\n  const add = (chord: Chord) => {\n    const dedupeKey = `${mod12(chord.rootPc)}:${chord.quality}`;\n    if (seen.has(dedupeKey)) {\n      return;\n    }\n    seen.add(dedupeKey);\n    palette.push({\n      chord,\n      roman: chordToRoman(chord, key),\n      source: borrowedSource(chord, key),\n    });\n  };\n\n  for (const triad of diatonicTriadsOf(parallelKey(key))) {\n    if (!isDiatonic(triad, key) && borrowedSource(triad, key) !== null) {\n      add(triad);\n    }\n  }\n  // The Neapolitan (major triad on b2) sits outside both parallel modes, so it\n  // is added explicitly — unless b2 is already diatonic (e.g. in a Phrygian key,\n  // where it is a native chord rather than a borrowing).\n  const neapolitan = makeChord(mod12(key.rootPc + 1), 'maj');\n  if (!isDiatonic(neapolitan, key)) {\n    add(neapolitan);\n  }\n  return palette;\n}\n\n/**\n * Reflect a chord across the tonic–dominant axis of a key (negative harmony).\n *\n * Every pitch class `p` maps to `(2*T + 7 - p) mod 12`, where `T` is the key\n * tonic — the reflection that swaps the tonic with the dominant. The mirrored\n * pitch classes (including the bass, if set) are reassembled into a chord by\n * {@link detectChordBest}; when no chord is recognized, the mirrored root and\n * the original quality are used as a fallback.\n *\n * @param chord The chord to reflect.\n * @param key The prevailing key.\n * @returns The negative-harmony counterpart of the chord.\n * @example\n * ```ts\n * import { negativeHarmonyMirror, makeChord, majorKey } from '@libraz/libcantus';\n * negativeHarmonyMirror(makeChord(7, 'maj'), majorKey(0));\n * // G major reflected across C's axis => F minor (rootPc 5, quality 'min')\n * ```\n * @category Reharmonization\n */\nexport function negativeHarmonyMirror(chord: Chord, key: KeyScale): Chord {\n  const tonic = mod12(key.rootPc);\n  const mirror = (p: number) => mod12(2 * tonic + 7 - p);\n  const pcs = chordPitchClasses(chord).map(mirror);\n  const bassPc = chord.bassPc !== undefined ? mirror(chord.bassPc) : undefined;\n  // Place the mirrored bass an octave below so it is recognized as the lowest\n  // note and preserved through detection.\n  const pitches = bassPc !== undefined ? [bassPc - 12, ...pcs] : pcs;\n  const detected = detectChordBest(pitches);\n  if (detected) {\n    // Without an input bass the mirrored tones are octave-less, so detection may\n    // read the lowest pitch class as a slash bass and report a spurious\n    // inversion. Restore the recognized chord to root position in that case.\n    if (bassPc === undefined && detected.bassPc !== undefined) {\n      return makeChord(detected.rootPc, detected.quality);\n    }\n    return detected;\n  }\n  const quality: ChordQuality = chord.quality;\n  return makeChord(mirror(chord.rootPc), quality, bassPc);\n}\n"]}