@libraz/libcantus 0.9.0

package/src/index.ts

@@ -0,0 +1,233 @@
+export type { AnalyzedNote, TheoryLabel, VoiceNote } from './analysis/index.js';
+export { analyzeVoice } from './analysis/index.js';
+export type {
+  ArrangementAnalysis,
+  ArrangementOptions,
+  ArrangementTrack,
+  Conflict,
+  TensionPoint,
+  TrackAnalysis,
+  TrackRole,
+} from './arrange/index.js';
+export { analyzeArrangement, tensionCurve } from './arrange/index.js';
+export type { BassLineOptions, BassSegment, BassStyle } from './bass/index.js';
+export { generateBassLine } from './bass/index.js';
+export type { Chord as ChordData, ChordQuality } from './chord/index.js';
+export {
+  chordFromDegree,
+  chordPitchClasses,
+  chordQualities,
+  chordToneRole,
+  diatonicSeventh,
+  diatonicTriad,
+  makeChord,
+} from './chord/index.js';
+export type { ChordScaleMatch, ChordScaleReportEntry, ScaleChoice } from './chordscale/index.js';
+export {
+  availableTensions,
+  avoidNotes,
+  chordScaleReport,
+  chordScales,
+  scaleMatchesChord,
+  scalesForChanges,
+} from './chordscale/index.js';
+export type { CounterMelodyOptions } from './countermelody/index.js';
+export { generateCounterMelody } from './countermelody/index.js';
+export {
+  createsHiddenParallelPerfect,
+  createsParallelOctave,
+  createsParallelPerfect,
+  createsParallelUnison,
+  createsVerticalDissonance,
+  createsVoiceCrossing,
+  createsVoiceOverlap,
+  exceedsSpacing,
+  isForbiddenMelodicLeap,
+  isLeadingToneResolution,
+} from './counterpoint/index.js';
+export type { ChordMatch, KeyMatch } from './detect/index.js';
+export { detectChord, detectChordBest, detectKey } from './detect/index.js';
+export type {
+  DrumGenOptions,
+  DrumHit,
+  DrumRole,
+  GrooveFeel,
+  GrooveStyle,
+  Section,
+} from './drums/index.js';
+export { generateDrums } from './drums/index.js';
+export type {
+  BorrowedSource,
+  Cadence,
+  ChordAnalysis,
+  HarmonicFunction,
+} from './functional/index.js';
+export {
+  analyzeChord,
+  borrowedSource,
+  chordToRoman,
+  detectCadence,
+  functionOf,
+  isBorrowedChord,
+  isDiatonic,
+  isMinorKey,
+  parallelKey,
+  romanToChord,
+  secondaryDominant,
+} from './functional/index.js';
+export type { GrooveSlot, GrooveTemplate, HumanizeOptions } from './groove/index.js';
+export { applyGrooveTemplate, extractGrooveTemplate, humanize } from './groove/index.js';
+export type {
+  HarmonizeOptions,
+  HarmonizeResult,
+  MelodyNote,
+} from './harmonize/index.js';
+export { harmonizeMelody } from './harmonize/index.js';
+export type { HarmonyRole, LockLevel, VoicedRole } from './harmony/index.js';
+export { roleOf } from './harmony/index.js';
+export {
+  classifyInterval,
+  IntervalQuality,
+  isConsonantInterval,
+  isPerfectInterval,
+} from './interval/index.js';
+export type { BarPosition, TimeSignature } from './meter/index.js';
+export {
+  barPositionToBeat,
+  beatsPerBar,
+  beatToBarPosition,
+  formatTimeSignature,
+  isCompound,
+  isStrongBeat,
+  metricWeight,
+  parseTimeSignature,
+  pulsesPerBar,
+  tuplet,
+} from './meter/index.js';
+export { Chord, Interval, Key, Note, Progression } from './model/index.js';
+export type {
+  GenerateMotifOptions,
+  MotifCell,
+  MotifContour,
+  MotifNote,
+  MotifTransform,
+} from './motif/index.js';
+export { developMotif, generateMotif, transformMotif } from './motif/index.js';
+export type { Note as NoteData, SpelledInterval } from './pitch/index.js';
+export {
+  formatNote,
+  midiToNote,
+  noteToMidi,
+  noteToPitchClass,
+  parseNote,
+  spelledInterval,
+} from './pitch/index.js';
+export type {
+  GeneratedChord,
+  GenerateProgressionOptions,
+  ProgFunction,
+  ProgressionPreset,
+  ProgStyle,
+} from './progression/index.js';
+export {
+  generateProgression,
+  progressions,
+  progressionsByStyle,
+} from './progression/index.js';
+export type { Rng } from './random/index.js';
+export { createRng } from './random/index.js';
+export type {
+  BorrowedChord,
+  SubstituteOptions,
+  Substitution,
+  SubstitutionType,
+} from './reharmony/index.js';
+export {
+  modalInterchangePalette,
+  negativeHarmonyMirror,
+  substituteChord,
+} from './reharmony/index.js';
+export type { RhythmEvent, RhythmOptions } from './rhythm/index.js';
+export { generateRhythm, onsetWeightCurve, rhythmDensity } from './rhythm/index.js';
+export type {
+  SafetyProfile,
+  SafetyQuery,
+  SafetyResult,
+  VoiceSnapshot,
+} from './safety/index.js';
+export { enumerateSafePitches, evaluateSafety, NoteSafety, ReasonFlag } from './safety/index.js';
+export {
+  BLUES_MASK,
+  CHROMATIC_MASK,
+  DORIAN_MASK,
+  diatonicPitchClasses,
+  HARMONIC_MINOR_MASK,
+  isScaleTone,
+  LOCRIAN_MASK,
+  LYDIAN_MASK,
+  MAJOR_MASK,
+  MAJOR_PENTATONIC_MASK,
+  MELODIC_MINOR_MASK,
+  MINOR_PENTATONIC_MASK,
+  MIXOLYDIAN_MASK,
+  majorKey,
+  maskFromOffsets,
+  minorKey,
+  NAMED_SCALES,
+  NATURAL_MINOR_MASK,
+  nearestScaleTone,
+  OCTATONIC_HALF_WHOLE_MASK,
+  OCTATONIC_WHOLE_HALF_MASK,
+  PHRYGIAN_MASK,
+  pitchToScaleDegree,
+  scaleByName,
+  scaleTonesInDegreeOrder,
+  WHOLE_TONE_MASK,
+} from './scale/index.js';
+export {
+  noteNames,
+  spellChord,
+  spellPitchClass,
+  spellPitchClasses,
+  spellScale,
+} from './spelling/index.js';
+export { formatChordSymbol, parseChordSymbol, transposeChordSymbol } from './symbol/index.js';
+export type {
+  CadenceHit,
+  ChordSegment,
+  ChordTimeline,
+  ChordTimelineOptions,
+  ChordTimelineResult,
+} from './timeline/index.js';
+export {
+  chordTimelineFromChords,
+  chordTimelineFromNotes,
+  detectCadences,
+} from './timeline/index.js';
+export type { Tuning } from './tuning/index.js';
+export {
+  centsBetweenFreq,
+  centsOfSteps,
+  edo,
+  frequencyOf,
+  JUST_RATIOS,
+  justDeviationCents,
+  nearestStep,
+  ratioToCents,
+  TWELVE_TET,
+} from './tuning/index.js';
+export type { KeyScale, NoteEvent } from './types.js';
+export type {
+  StyledVoicingOptions,
+  VoiceRange,
+  VoicingOptions,
+  VoicingStyle,
+} from './voicing/index.js';
+export {
+  nextVoicing,
+  SATB_RANGES,
+  voiceChord,
+  voiceChordStyled,
+  voiceLeadingCost,
+  voiceProgression,
+} from './voicing/index.js';

package/src/interval/index.ts

@@ -0,0 +1,67 @@
+/** Counterpoint classification of a harmonic interval. */
+export enum IntervalQuality {
+  PerfectConsonance = 0,
+  ImperfectConsonance = 1,
+  Dissonance = 2,
+}
+
+/** Reduce an interval to a simple interval class in the range [0, 11]. */
+function simpleInterval(semitones: number): number {
+  return Math.abs(semitones) % 12;
+}
+
+/**
+ * Classify an interval for counterpoint evaluation.
+ *
+ * The interval is reduced modulo 12, so compound intervals classify as their
+ * simple equivalents. The perfect fourth (5) is context-dependent: with
+ * `twoVoice` (the default) it classifies as a dissonance, matching
+ * {@link isConsonantInterval}; otherwise it is an imperfect consonance.
+ *
+ * @param semitones Interval size in semitones (may be negative or compound).
+ * @param twoVoice When true, the perfect fourth is treated as dissonant.
+ * @returns The counterpoint quality of the interval.
+ */
+export function classifyInterval(semitones: number, twoVoice = true): IntervalQuality {
+  const pc = simpleInterval(semitones);
+  if (pc === 0 || pc === 7) {
+    return IntervalQuality.PerfectConsonance;
+  }
+  if (pc === 3 || pc === 4 || pc === 8 || pc === 9) {
+    return IntervalQuality.ImperfectConsonance;
+  }
+  if (pc === 5) {
+    return twoVoice ? IntervalQuality.Dissonance : IntervalQuality.ImperfectConsonance;
+  }
+  return IntervalQuality.Dissonance;
+}
+
+/**
+ * Test whether an interval is a perfect interval (unison/octave or fifth).
+ *
+ * @param semitones Interval size in semitones (may be negative or compound).
+ * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.
+ */
+export function isPerfectInterval(semitones: number): boolean {
+  const pc = simpleInterval(semitones);
+  return pc === 0 || pc === 7;
+}
+
+/**
+ * Test whether an interval is consonant.
+ *
+ * The consonant set is {0, 3, 4, 5, 7, 8, 9} mod 12. In two-voice counterpoint
+ * the perfect fourth (5) is treated as a dissonance, so `twoVoice` set to true
+ * excludes it.
+ *
+ * @param semitones Interval size in semitones (may be negative or compound).
+ * @param twoVoice When true, the perfect fourth is treated as dissonant.
+ * @returns True if the interval is consonant in the given context.
+ */
+export function isConsonantInterval(semitones: number, twoVoice = true): boolean {
+  const pc = simpleInterval(semitones);
+  if (pc === 5) {
+    return !twoVoice;
+  }
+  return pc === 0 || pc === 3 || pc === 4 || pc === 7 || pc === 8 || pc === 9;
+}

package/src/meter/index.ts

@@ -0,0 +1,179 @@
+/**
+ * Meter and time signatures: bar/beat arithmetic, simple vs. compound meters,
+ * metric-accent hierarchy, and tuplet subdivision.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the rest
+ * of the library's beat convention (four quarter-note beats per bar in 4/4).
+ */
+
+/** A time signature as a numerator over a note-value denominator. */
+export type TimeSignature = {
+  numerator: number;
+  denominator: number;
+};
+
+/** A position expressed as a bar index and a quarter-note offset within the bar. */
+export type BarPosition = {
+  bar: number;
+  /** Quarter-note offset from the start of the bar. */
+  beat: number;
+};
+
+const EPS = 1e-9;
+
+/** Whether `value` is an integer multiple of `unit` (within a float tolerance). */
+function isMultiple(value: number, unit: number): boolean {
+  if (unit === 0) {
+    return false;
+  }
+  const ratio = value / unit;
+  return Math.abs(ratio - Math.round(ratio)) < EPS;
+}
+
+/**
+ * Parse a time signature such as `"4/4"` or `"6/8"`.
+ *
+ * @param text The signature text.
+ * @returns The parsed time signature.
+ * @throws If the text is not `n/d` with positive integers.
+ */
+export function parseTimeSignature(text: string): TimeSignature {
+  const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(text);
+  if (!match) {
+    throw new Error(`Invalid time signature: ${text}`);
+  }
+  const numerator = Number.parseInt(match[1] ?? '', 10);
+  const denominator = Number.parseInt(match[2] ?? '', 10);
+  if (numerator <= 0 || denominator <= 0) {
+    throw new Error(`Invalid time signature: ${text}`);
+  }
+  return { numerator, denominator };
+}
+
+/** Render a time signature as `"n/d"`. */
+export function formatTimeSignature(ts: TimeSignature): string {
+  return `${ts.numerator}/${ts.denominator}`;
+}
+
+/**
+ * Whether a meter is compound: its main pulses each divide into three, as in
+ * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a
+ * multiple of three greater than three, independent of the denominator. Meters
+ * like 3/8 and 3/4 (simple triples, numerator 3) are not compound.
+ *
+ * @param ts The time signature.
+ * @returns True for compound meters.
+ */
+export function isCompound(ts: TimeSignature): boolean {
+  return ts.numerator % 3 === 0 && ts.numerator > 3;
+}
+
+/** Length of one denominator unit in quarter-note beats. */
+function unitBeats(ts: TimeSignature): number {
+  return 4 / ts.denominator;
+}
+
+/**
+ * Length of a bar in quarter-note beats.
+ *
+ * @param ts The time signature.
+ * @returns The bar length in quarter notes.
+ */
+export function beatsPerBar(ts: TimeSignature): number {
+  return ts.numerator * unitBeats(ts);
+}
+
+/** Length of one main pulse (a dotted value in compound meters) in quarter notes. */
+function pulseBeats(ts: TimeSignature): number {
+  return isCompound(ts) ? 3 * unitBeats(ts) : unitBeats(ts);
+}
+
+/**
+ * Number of main pulses (felt beats) per bar: the numerator for simple meters,
+ * a third of it for compound meters.
+ *
+ * @param ts The time signature.
+ * @returns The pulse count per bar.
+ */
+export function pulsesPerBar(ts: TimeSignature): number {
+  return beatsPerBar(ts) / pulseBeats(ts);
+}
+
+/**
+ * Convert an absolute quarter-note position to a bar index and in-bar offset.
+ *
+ * @param beatInQuarters Absolute position in quarter-note beats.
+ * @param ts The time signature.
+ * @returns The bar and in-bar quarter-note offset.
+ */
+export function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition {
+  const barLen = beatsPerBar(ts);
+  const bar = Math.floor(beatInQuarters / barLen);
+  return { bar, beat: beatInQuarters - bar * barLen };
+}
+
+/**
+ * Convert a bar index and in-bar offset back to an absolute quarter-note
+ * position.
+ *
+ * @param pos The bar position.
+ * @param ts The time signature.
+ * @returns The absolute position in quarter-note beats.
+ */
+export function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number {
+  return pos.bar * beatsPerBar(ts) + pos.beat;
+}
+
+/**
+ * Metric weight of a position within its bar, on a 0–3 scale:
+ * 3 the downbeat, 2 a secondary strong pulse (the bar's midpoint in even
+ * meters), 1 any other main pulse, and 0 an off-pulse subdivision.
+ *
+ * @param beatInQuarters Absolute or in-bar quarter-note position.
+ * @param ts The time signature.
+ * @returns The metric weight (0–3).
+ */
+export function metricWeight(beatInQuarters: number, ts: TimeSignature): number {
+  const { beat } = beatToBarPosition(beatInQuarters, ts);
+  const pulse = pulseBeats(ts);
+  if (!isMultiple(beat, pulse)) {
+    return 0;
+  }
+  const pulses = pulsesPerBar(ts);
+  const pulseIndex = Math.round(beat / pulse) % pulses;
+  if (pulseIndex === 0) {
+    return 3;
+  }
+  if (pulses % 2 === 0 && pulseIndex === pulses / 2) {
+    return 2;
+  }
+  return 1;
+}
+
+/**
+ * Whether a position is metrically accented (weight 2 or more — a downbeat or a
+ * secondary strong pulse).
+ *
+ * @param beatInQuarters Absolute or in-bar quarter-note position.
+ * @param ts The time signature.
+ * @returns True on strong beats.
+ */
+export function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean {
+  return metricWeight(beatInQuarters, ts) >= 2;
+}
+
+/**
+ * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note
+ * triplet is `tuplet(1, 3)`).
+ *
+ * @param totalBeats Total span in quarter-note beats.
+ * @param count Number of equal parts.
+ * @returns `count` equal durations summing to `totalBeats`.
+ * @throws If `count` is not a positive integer.
+ */
+export function tuplet(totalBeats: number, count: number): number[] {
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new Error(`Invalid tuplet count: ${count}`);
+  }
+  return new Array<number>(count).fill(totalBeats / count);
+}