@libraz/libcantus 1.1.0 → 1.3.0

package/dist/{chunk-DKICR7AN.js → chunk-IPEF6NWB.js}

@@ -1,20 +1,16 @@
 import {
   analyzeArrangement,
   analyzePolyphony,
+  analyzeReference,
   createArrangementSession,
-  extractMotifs,
   hypermeter,
-  melodicContour,
-  melodicSimilarity,
-  motifFromNotes,
   phrasesFromTimeline,
-  reduceProgression,
-  relateMotifs,
+  referenceFromReadings,
   sectionsFromNotes,
   structuralCadences,
   tensionCurveFrom,
   trackRoleOf
-} from "./chunk-HSY2VQXZ.js";
+} from "./chunk-MLBPXA4Z.js";
 import {
   TWELVE_TET,
   beatsToDuration,
@@ -38,18 +34,21 @@ import {
   tempoAt,
   tempoReader,
   ticksToBeats
-} from "./chunk-HOHFYGKW.js";
+} from "./chunk-UMWZ4ZET.js";
 import {
   STEP_BEATS,
   applyGrooveTemplate,
   cellSpan,
   deform,
+  deriveCompositionPlan,
   developMotif,
   doubleTime,
+  evaluateComposition,
   extractGrooveTemplate,
   generateBassLine,
   generateCounterMelody,
   generateDrums,
+  generateMelody,
   generateMotif,
   generateProgression,
   generateRhythm,
@@ -69,9 +68,10 @@ import {
   thin,
   transformMotif,
   withinCeiling
-} from "./chunk-R5VUXQMP.js";
+} from "./chunk-CPMB7P75.js";
 import {
   analyzeChord,
+  analyzeRhythm,
   augmentedSixthChord,
   borrowedSource,
   chordAtBeat,
@@ -87,17 +87,24 @@ import {
   detectKeyFromNotes,
   detectModulations,
   explainRoman,
+  extractMotifs,
   functionOf,
   isBorrowedChord,
   isMinorKey,
   keyLookup,
   keyTimelineFromNotes,
+  melodicContour,
+  melodicSimilarity,
+  motifFromNotes,
+  motifGraph,
   pivotChords,
   prevailingKeyOf,
+  reduceProgression,
+  relateMotifs,
   romanToChord,
   secondaryDominantOf,
   toVoiceNotes
-} from "./chunk-VLE5R7PF.js";
+} from "./chunk-GNVN4PPJ.js";
 import {
   BASS_4_STRING,
   BASS_5_STRING,
@@ -110,10 +117,10 @@ import {
   soundsIn,
   toInstrumentProfile,
   toStringedProfile
-} from "./chunk-X6RJAHII.js";
+} from "./chunk-7KG3RTYS.js";
 import {
   createNoteEventIndex
-} from "./chunk-7GOKQJTQ.js";
+} from "./chunk-PUKJP2Z5.js";
 import {
   SATB_RANGES,
   checkPartWriting,
@@ -128,14 +135,14 @@ import {
   voiceChordStyled,
   voiceLeadingCost,
   voiceProgression
-} from "./chunk-AWEMD747.js";
+} from "./chunk-M5RYMAFI.js";
 import {
   availableTensions,
   avoidNotes,
   chordScaleReport,
   chordScales,
   scalesForChanges
-} from "./chunk-H66ARFU5.js";
+} from "./chunk-NB25P3EH.js";
 import {
   NAMED_SCALES,
   assertChordQuality,
@@ -191,7 +198,7 @@ import {
   tryResolveKeyName,
   variantOfMask,
   voiceIndependence
-} from "./chunk-FPBZFNCD.js";
+} from "./chunk-RFIBF2RR.js";
 import {
   InvalidInputError,
   MAX_NAME_ACCIDENTALS,
@@ -235,7 +242,7 @@ import {
   tryParseTimeSignature,
   tuplet,
   unwrapParse
-} from "./chunk-PQL7E5F6.js";
+} from "./chunk-AGOVW7U6.js";
 
 // src/model/interval.ts
 var INVERSION_SUM = 9;
@@ -4411,6 +4418,8 @@ var Score = class _Score {
   #chords;
   /** The key regions, made on the first member that needs them. */
   #regions;
+  /** The reference profile asked for with no options, made on first read. */
+  #profile;
   /**
    * Wrap plain score data.
    *
@@ -4898,6 +4907,143 @@ var Score = class _Score {
   contour() {
     return melodicContour(this.#data.notes);
   }
+  /**
+   * The score's structural fingerprint: form, phrase shape, harmonic function
+   * and rhythm, and how its motifs derive from one another.
+   *
+   * The harmony is the score's own kept chord analysis, read once whether this
+   * is asked before or after {@link Score.timeline} — unless `opts.timeline`
+   * gives the harmony directly, in which case the reading runs fresh through
+   * {@link analyzeReference} rather than the harmony this score already holds.
+   * The meter, the key and the span are the score's own and are not on offer
+   * here: a caller wanting another meter reads through {@link
+   * Score.withMeters}, and one wanting another key or span calls {@link
+   * analyzeReference} directly.
+   *
+   * Asked with no options, the answer is kept and a copy of it handed back, as
+   * {@link Score.timeline} keeps its own reading; asked with options, the
+   * answer is read afresh and not kept.
+   *
+   * @param opts The harmony, the melody, and the budget; see {@link
+   *   ReferenceProfileOptions}. Meter, key and span are the score's own.
+   * @returns The profile.
+   * @example
+   * ```ts
+   * import { Score } from '@libraz/libcantus';
+   * const triad = (pitches: number[], startBeat: number) =>
+   *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
+   * const score = Score.of(
+   *   [
+   *     ...triad([60, 64, 67], 0),
+   *     ...triad([65, 69, 72], 4),
+   *     ...triad([67, 71, 74], 8),
+   *     ...triad([60, 64, 67], 12),
+   *   ],
+   *   { key: 'C major' },
+   * );
+   * score.reference().harmony.chords.map((chord) => chord.roman); // ['I', 'IV', 'V', 'I']
+   * ```
+   */
+  reference(opts) {
+    if (opts === void 0 && this.#profile !== void 0) {
+      return copyPlain(this.#profile, "reference profile");
+    }
+    const keyed = this.#key === void 0 ? {} : { key: keyIdentity(this.#key) };
+    const asked = {
+      meters: this.#data.meters,
+      totalBeats: this.totalBeats,
+      ...keyed,
+      ...opts
+    };
+    const profile = opts?.timeline === void 0 ? referenceFromReadings(this.#data.notes, this.#chordAnalysis(), asked) : analyzeReference(this.#data.notes, asked);
+    if (opts === void 0) {
+      this.#profile = profile;
+      return copyPlain(profile, "reference profile");
+    }
+    return profile;
+  }
+  /**
+   * The onset placement of the score's melodic line.
+   *
+   * A melody is one line, so a score holding several is read as its top voice,
+   * as {@link Score.motifs} and {@link Score.contour} are.
+   *
+   * @param opts The span's end and the budget; see {@link
+   *   RhythmAnalysisOptions}. The meter is the score's own.
+   * @returns The rhythm reading.
+   * @example
+   * ```ts
+   * import { Score } from '@libraz/libcantus';
+   * const score = Score.of([
+   *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+   *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+   *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+   *   { pitch: 65, startBeat: 3, durationBeat: 1 },
+   * ]);
+   * score.rhythm().onsetDensity; // 4
+   * ```
+   */
+  rhythm(opts) {
+    return analyzeRhythm(this.#data.notes, {
+      meters: this.#data.meters,
+      totalBeats: this.totalBeats,
+      ...opts
+    });
+  }
+  /**
+   * How the score's motifs derive from one another: which statement grew out
+   * of which, and by what transformation.
+   *
+   * {@link Score.motifs} finds the cells; this reads across their occurrences
+   * and names, for every statement after the first, the earlier one it most
+   * plausibly grew out of. A melody is one line, so a score holding several is
+   * read as its top voice, as {@link Score.motifs} is.
+   *
+   * @param opts Cell-length bounds and the recurrence threshold {@link
+   *   Score.motifs} takes, plus the variation threshold and the budget; see
+   *   {@link MotifGraphOptions} and {@link ExtractMotifsOptions}.
+   * @returns The derivation forest.
+   * @example
+   * ```ts
+   * import { Score } from '@libraz/libcantus';
+   * const score = Score.of([
+   *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+   *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+   *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+   *   { pitch: 60, startBeat: 3, durationBeat: 1 },
+   *   { pitch: 62, startBeat: 4, durationBeat: 1 },
+   *   { pitch: 64, startBeat: 5, durationBeat: 1 },
+   * ]);
+   * score.motifGraph().edges.length; // 1
+   * ```
+   */
+  motifGraph(opts) {
+    return motifGraph(this.#data.notes, extractMotifs(this.#data.notes, opts), {
+      key: this.key(),
+      ...opts
+    });
+  }
+  /**
+   * How this score, read as a melody, keeps to a composition plan.
+   *
+   * @param plan The plan the melody was written for.
+   * @param opts The budget; see {@link EvaluateCompositionOptions}.
+   * @returns The violations found and the fit reading; see {@link
+   *   evaluateComposition}.
+   * @example
+   * ```ts
+   * import { Composer, Score } from '@libraz/libcantus';
+   * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+   *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+   * );
+   * const composer = Composer.of({ key: 'C major', seed: 5 });
+   * const plan = composer.plan(Score.of(notes, { key: 'C major' }).reference());
+   * composer.melody(plan).evaluate(plan).violations.some((v) => v.severity === 'error'); // false
+   * ```
+   */
+  evaluate(plan, opts) {
+    return evaluateComposition(this.#data.notes, plan, opts);
+  }
   /**
    * Each note's role in the harmony sounding under it.
    *
@@ -5532,6 +5678,70 @@ var Arrangement = class _Arrangement {
       keys: [...keys]
     });
   }
+  /**
+   * The arrangement's structural fingerprint: form, phrase shape, harmonic
+   * function and rhythm, and how its melody's motifs derive from one another.
+   *
+   * The harmony reads the arrangement's own session analysis directly — the
+   * tracks `settings.harmonyTracks` names, or else every track but the
+   * percussion ones — so the harmony is never inferred a second time. The
+   * melody is the notes of the tracks played with `role: 'melody'`, joined in
+   * the order the tracks were given; an arrangement naming none reads the top
+   * line of the harmony notes instead, as {@link analyzeReference} does
+   * without a `melody` option. Meter, key, harmony and melody are the
+   * arrangement's own and are not on offer here: a caller wanting others calls
+   * {@link analyzeReference} directly, with the same notes {@link
+   * Arrangement.tracks} hands out.
+   *
+   * @param opts The budget; see {@link ReferenceProfileOptions}.
+   * @returns The profile.
+   * @example
+   * ```ts
+   * import { Arrangement } from '@libraz/libcantus';
+   * const triad = (pitches: number[], startBeat: number) =>
+   *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
+   * const arrangement = Arrangement.of(
+   *   [
+   *     {
+   *       name: 'lead',
+   *       role: 'melody',
+   *       notes: [
+   *         ...triad([60, 64, 67], 0),
+   *         ...triad([65, 69, 72], 4),
+   *         ...triad([67, 71, 74], 8),
+   *         ...triad([60, 64, 67], 12),
+   *       ],
+   *     },
+   *   ],
+   *   { key: 'C major' },
+   * );
+   * arrangement.reference().harmony.chords.map((chord) => chord.roman); // ['I', 'IV', 'V', 'I']
+   * ```
+   */
+  reference(opts) {
+    const tracks = this.#data.tracks;
+    const harmonyTracks = this.#data.settings?.harmonyTracks;
+    const harmony = [];
+    const melody = [];
+    for (let index = 0; index < tracks.length; index += 1) {
+      const track = tracks[index];
+      if (track === void 0) {
+        continue;
+      }
+      if (track.role !== "drums" && (harmonyTracks === void 0 || harmonyTracks.includes(index))) {
+        harmony.push(...track.notes);
+      }
+      if (track.role === "melody") {
+        melody.push(...track.notes);
+      }
+    }
+    return referenceFromReadings(harmony, this.#session().analysis, {
+      meters: this.#data.settings?.meters,
+      totalBeats: this.timeline().totalBeats,
+      ...melody.length === 0 ? {} : { melody },
+      ...opts
+    });
+  }
   /**
    * Whether another arrangement holds the same tracks under the same settings.
    *
@@ -6228,6 +6438,73 @@ var Composer = class _Composer {
       transposeSemitones: result.transposeSemitones
     };
   }
+  /**
+   * A composition plan derived from a reference profile.
+   *
+   * The composer's key is the plan's home key unless `opts.key` names another,
+   * and its seed and algorithm version are the ones the plan records, so the
+   * plan is written under the same recipe as the composer's other parts.
+   *
+   * @param reference The reference profile to derive from.
+   * @param opts Everything {@link deriveCompositionPlan} takes but the context,
+   *   which is the composer's.
+   * @returns The plan.
+   * @throws If the composer draws from a caller-held `rng`: a plan records its
+   *   seed, and a source cannot be written into it.
+   * @example
+   * ```ts
+   * import { Composer, Score } from '@libraz/libcantus';
+   * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+   *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+   * );
+   * const reference = Score.of(notes, { key: 'C major' }).reference();
+   * const plan = Composer.of({ key: 'D major', seed: 5 }).plan(reference);
+   * plan.seed; // 5
+   * plan.keys[0].scale.rootPc; // 2
+   * ```
+   */
+  plan(reference, opts) {
+    const ctx = this.context;
+    if (ctx.rng !== void 0) {
+      throw new InvalidInputError(
+        "composer plan cannot record a caller-held rng; give the composer a seed instead"
+      );
+    }
+    return deriveCompositionPlan(reference, {
+      ...this.#key === void 0 ? {} : { key: this.#key },
+      ...opts,
+      ctx
+    });
+  }
+  /**
+   * A melody written to a composition plan.
+   *
+   * The plan is the reproduction recipe, so its seed and algorithm version are
+   * the ones the melody is drawn under, not the composer's. The score is read
+   * in the plan's meter and home key, at the composer's tempo.
+   *
+   * @param plan The plan to follow.
+   * @param opts The budget; see {@link MelodyOptions}.
+   * @returns The melody, as a score.
+   * @example
+   * ```ts
+   * import { Composer, Score } from '@libraz/libcantus';
+   * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+   *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+   * );
+   * const composer = Composer.of({ key: 'C major', seed: 5 });
+   * const plan = composer.plan(Score.of(notes, { key: 'C major' }).reference());
+   * composer.melody(plan).notes.length > 0; // true
+   * ```
+   */
+  melody(plan, opts) {
+    const notes = generateMelody(plan, opts);
+    const score = { meters: plan.meters, key: plan.keys[0] };
+    if (this.#options.bpm !== void 0) {
+      score.tempo = this.#options.bpm;
+    }
+    return Score.of(notes, score);
+  }
   /**
    * Whether another composer holds the same settings.
    *
@@ -8106,7 +8383,8 @@ var Voicing = class _Voicing {
    * @param pitch The candidate MIDI pitch.
    * @param query The candidate's harmonic and voice-leading context.
    * @param opts Set `suggestions: false` to skip the search for safe
-   *   replacements when the verdict is not safe.
+   *   replacements when the verdict is not safe, and `partners: true` to learn
+   *   which voice of this voicing, by index, raised each pairwise flag.
    * @returns The verdict, reason bitmask, and optional resolution guidance.
    * @throws If the profile is unknown, a value names no chord or key, or a
    *   pitch is not a MIDI pitch in 0..127.
@@ -8249,4 +8527,4 @@ export {
   Tuning,
   Voicing
 };
-//# sourceMappingURL=chunk-DKICR7AN.js.map
+//# sourceMappingURL=chunk-IPEF6NWB.js.map