@libraz/libcantus 0.9.2 → 0.9.4

package/src/generate/rhythm/index.ts

@@ -1,165 +0,0 @@
-/**
- * Deterministic rhythm generation over a metric grid.
- *
- * Builds a fixed-resolution grid across one or more bars of a time signature
- * and decides, per grid slot, whether it becomes a note onset. Onset
- * probability follows the metric-accent hierarchy from the `meter` module, so
- * strong positions (downbeats, secondary pulses) are favored over weak
- * off-pulse subdivisions. Given a seed the output is fully reproducible.
- *
- * Positions and durations are measured in quarter-note beats, matching the
- * library-wide convention.
- */
-
-import { beatsPerBar, metricWeight, type TimeSignature } from '../../core/meter/index.js';
-import { createRng } from '../../core/random/index.js';
-
-/**
- * A single rhythmic note: an onset position and how long it sounds.
- *
- * @category Rhythm & Meter
- */
-export type RhythmEvent = {
-  /** Onset position in quarter-note beats, absolute from the start of the span. */
-  position: number;
-  /** Duration in quarter-note beats, extending to the next onset. */
-  duration: number;
-};
-
-/**
- * Options controlling {@link generateRhythm}.
- *
- * @category Rhythm & Meter
- */
-export type RhythmOptions = {
-  /**
-   * Seed for the deterministic PRNG.
-   *
-   * @defaultValue 0
-   */
-  seed?: number;
-  /**
-   * Number of bars to generate.
-   *
-   * @defaultValue 1
-   */
-  bars?: number;
-  /**
-   * Grid resolution as the number of equal grid steps per quarter-note beat.
-   * The default of 2 yields an eighth-note grid; 4 yields a sixteenth-note
-   * grid, 3 an eighth-note triplet grid, and so on.
-   *
-   * @defaultValue 2
-   */
-  subdivision?: number;
-  /**
-   * Overall onset density in [0, 1]. Scales the per-slot onset probability, so
-   * higher values fill more grid slots. Values outside [0, 1] are clamped into
-   * range.
-   *
-   * @defaultValue 0.5
-   */
-  density?: number;
-};
-
-const DEFAULT_SUBDIVISION = 2;
-const DEFAULT_DENSITY = 0.5;
-const DEFAULT_BARS = 1;
-
-/**
- * Map a metric weight (0–3 from {@link metricWeight}) to a base onset
- * probability before density scaling. Strong positions are much more likely to
- * carry an onset than weak ones; the curve is intentionally small and explicit
- * so its behavior is easy to inspect and test.
- *
- * @param weight The metric weight, 0 (off-pulse) to 3 (downbeat).
- * @returns A base onset probability in [0, 1].
- * @category Rhythm & Meter
- */
-export function onsetWeightCurve(weight: number): number {
-  switch (weight) {
-    case 3:
-      return 1;
-    case 2:
-      return 0.8;
-    case 1:
-      return 0.55;
-    default:
-      return 0.25;
-  }
-}
-
-/**
- * Generate a deterministic rhythmic pattern over `bars` bars of a time
- * signature. A grid is built at the chosen subdivision; each slot becomes an
- * onset with a probability derived from its metric weight scaled by `density`
- * and sampled from the seeded PRNG. Every bar's downbeat is always an onset, so
- * a pattern of any length has a reliable pulse independent of the seed. Each
- * event's duration extends to the next onset, and the last event extends to the
- * end of the span. `density` is clamped to [0, 1].
- *
- * @param ts The time signature.
- * @param opts Generation options.
- * @returns Onset events sorted by position, non-overlapping, covering the span.
- * @example
- * ```ts
- * import { parseTimeSignature, generateRhythm } from '@libraz/libcantus';
- * const ts = parseTimeSignature('4/4');
- * generateRhythm(ts, { seed: 42, density: 0.6 }); // onset events over one bar
- * ```
- * @category Rhythm & Meter
- */
-export function generateRhythm(ts: TimeSignature, opts: RhythmOptions = {}): RhythmEvent[] {
-  const seed = opts.seed ?? 0;
-  const bars = opts.bars ?? DEFAULT_BARS;
-  const subdivision = opts.subdivision ?? DEFAULT_SUBDIVISION;
-  const density = Math.min(1, Math.max(0, opts.density ?? DEFAULT_DENSITY));
-
-  const barBeats = beatsPerBar(ts);
-  const spanBeats = barBeats * bars;
-  const step = 1 / subdivision;
-  const slotCount = Math.round(spanBeats * subdivision);
-  const slotsPerBar = Math.round(barBeats * subdivision);
-  const rng = createRng(seed);
-
-  const positions: number[] = [];
-  for (let i = 0; i < slotCount; i += 1) {
-    const position = i * step;
-    // Force every bar's downbeat so the pulse is reliable regardless of seed.
-    if (i % slotsPerBar === 0) {
-      positions.push(position);
-      continue;
-    }
-    const weight = metricWeight(position, ts);
-    const probability = onsetWeightCurve(weight) * density;
-    if (rng.prob(probability)) {
-      positions.push(position);
-    }
-  }
-
-  const events: RhythmEvent[] = [];
-  for (let i = 0; i < positions.length; i += 1) {
-    const position = positions[i] ?? 0;
-    const nextPosition = positions[i + 1] ?? spanBeats;
-    events.push({ position, duration: nextPosition - position });
-  }
-  return events;
-}
-
-/**
- * Onset density of a generated pattern: the mean number of onsets per bar.
- *
- * @param events Events from {@link generateRhythm}.
- * @param ts The time signature.
- * @returns The onset count divided by the number of bars the events span.
- * @category Rhythm & Meter
- */
-export function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number {
-  if (events.length === 0) {
-    return 0;
-  }
-  const last = events[events.length - 1];
-  const spanBeats = (last?.position ?? 0) + (last?.duration ?? 0);
-  const bars = spanBeats / beatsPerBar(ts);
-  return bars > 0 ? events.length / bars : 0;
-}

package/src/index.ts

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