@libraz/libcantus 0.9.0 → 0.9.2

package/dist/index-DZ1M21do.d.cts

@@ -0,0 +1,127 @@
+import { K as KeyScale } from './types-MGP29r3t.cjs';
+import { C as Chord } from './index-BOBXBNwP.cjs';
+
+/**
+ * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
+ *
+ * @category Arrangement & Analysis
+ */
+type SafetyProfile = 'strict' | 'pop';
+/**
+ * Overall placeability verdict for a candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
+declare enum NoteSafety {
+    Safe = 0,
+    Warning = 1,
+    Dissonant = 2
+}
+/**
+ * Bit flags describing why a pitch received its verdict.
+ *
+ * @category Arrangement & Analysis
+ */
+declare enum ReasonFlag {
+    ChordTone = 1,
+    Tension = 2,
+    AvoidNote = 4,
+    ScaleTone = 8,
+    NonScale = 16,
+    OutOfRange = 32,
+    Tritone = 64,
+    LargeLeap = 128,
+    MinorSecond = 256,
+    MajorSeventh = 512,
+    VerticalDissonance = 1024,
+    ParallelPerfect = 2048,
+    HiddenParallel = 4096,
+    VoiceCrossing = 8192,
+    Suspension = 16384,
+    NeedsResolution = 32768
+}
+/**
+ * A neighbouring voice's current and previous pitch.
+ *
+ * @category Arrangement & Analysis
+ */
+type VoiceSnapshot = {
+    pitch: number;
+    prevPitch?: number;
+};
+/**
+ * Everything needed to evaluate one candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
+type SafetyQuery = {
+    profile: SafetyProfile;
+    candidatePitch: number;
+    prevPitch?: number;
+    chord: Chord | null;
+    key: KeyScale;
+    otherVoices: VoiceSnapshot[];
+    strongBeat: boolean;
+    vocalLow?: number;
+    vocalHigh?: number;
+};
+/**
+ * The verdict, reason flags, and optional resolution guidance.
+ *
+ * @category Arrangement & Analysis
+ */
+type SafetyResult = {
+    safety: NoteSafety;
+    reasons: number;
+    resolveTo?: number;
+    suggestions?: number[];
+    rationale?: string;
+};
+/**
+ * Evaluate the safety of placing a candidate pitch in a voice.
+ *
+ * Reasons are merged from harmonic context (chord tone / tension / avoid / scale)
+ * and counterpoint (vertical dissonance, parallels, voice crossing). The `strict`
+ * profile treats avoid notes and parallels as dissonant; `pop` treats them as
+ * warnings. The final verdict is the worst severity among the reasons.
+ *
+ * @param q The candidate and its harmonic/voice-leading context.
+ * @returns The verdict, reason bitmask, and optional resolution guidance.
+ * @example
+ * ```ts
+ * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';
+ * const result = evaluateSafety({
+ *   profile: 'pop',
+ *   candidatePitch: 60, // C over a C major chord
+ *   chord: makeChord(0, 'maj'),
+ *   key: majorKey(0),
+ *   otherVoices: [],
+ *   strongBeat: true,
+ * });
+ * result.safety === NoteSafety.Safe; // true — C is a chord tone
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function evaluateSafety(q: SafetyQuery): SafetyResult;
+/**
+ * Enumerate placeable pitches in a range, chord tones first, descending.
+ *
+ * @param q The safety context minus the candidate pitch.
+ * @param pitchLow Lowest MIDI pitch to consider (inclusive).
+ * @param pitchHigh Highest MIDI pitch to consider (inclusive).
+ * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
+ * @example
+ * ```ts
+ * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
+ * const pitches = enumerateSafePitches(
+ *   { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },
+ *   60,
+ *   72,
+ * );
+ * pitches; // placeable pitches in [60, 72], chord tones first, each group descending
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
+
+export { NoteSafety as N, ReasonFlag as R, type SafetyProfile as S, type VoiceSnapshot as V, type SafetyQuery as a, type SafetyResult as b, evaluateSafety as c, enumerateSafePitches as e };

package/dist/index-D_ZTUNKp.d.cts

@@ -0,0 +1,151 @@
+import { T as TimeSignature } from './index-Cl7mhOFM.cjs';
+import { K as KeyScale, N as NoteEvent } from './types-MGP29r3t.cjs';
+import { C as Chord, b as ChordSpan } from './index-BOBXBNwP.cjs';
+import { C as Cadence } from './function-r2sh-jOO.cjs';
+
+/**
+ * A chord occupying a half-open beat span.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordSegment = {
+    startBeat: number;
+    endBeat: number;
+    chord: Chord;
+};
+/**
+ * A beat-indexed sequence of chord segments.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordTimeline = {
+    /** The chord sounding at a beat, or null when no segment covers it. */
+    at: (beat: number) => Chord | null;
+    segments: ChordSegment[];
+};
+/**
+ * Build a chord timeline from placed chords.
+ *
+ * Each chord spans from its `startBeat` to the next chord's `startBeat`; the last
+ * chord runs to `totalBeats`. Segments with no positive length (from duplicate
+ * onsets or a last chord at or past `totalBeats`) are dropped. `at(beat)` returns
+ * the covering segment's chord, or null when the beat lies outside every segment.
+ *
+ * @param chords Placed chords in time order.
+ * @param totalBeats End of the timeline in beats.
+ * @returns A queryable chord timeline.
+ * @category Arrangement & Analysis
+ */
+declare function chordTimelineFromChords(chords: ChordSpan[], totalBeats: number): ChordTimeline;
+/**
+ * Options controlling {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordTimelineOptions = {
+    /** Key context; inferred from the notes with {@link detectKey} when omitted. */
+    key?: KeyScale;
+    /**
+     * Time signature used for metric accents; defaults to 4/4.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: TimeSignature;
+    /**
+     * Window length in beats per chord slot; defaults to one bar of `ts`.
+     *
+     * @defaultValue one bar of `ts`
+     */
+    harmonicRhythm?: number;
+    /**
+     * End of the analyzed span in beats; defaults to the end of the last note.
+     *
+     * @defaultValue the end of the last note
+     */
+    totalBeats?: number;
+};
+/**
+ * The result of {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordTimelineResult = {
+    /** The inferred timeline, with adjacent identical chords merged. */
+    timeline: ChordTimeline;
+    /** The key used for the analysis (given or inferred). */
+    key: KeyScale;
+    /** One confidence value in [0, 1] per segment, in segment order. */
+    segmentConfidence: number[];
+};
+/**
+ * Infer a chord timeline from raw multi-track notes.
+ *
+ * The span `[0, totalBeats)` is sliced into `harmonicRhythm`-beat windows; each
+ * window's chord is inferred from a pitch-class weight histogram of the notes
+ * overlapping it (weight = overlap duration x velocity x metric-accent bonus
+ * for onsets in the window). Adjacent windows carrying the identical chord are
+ * merged into one segment; windows with no notes produce no segment, so
+ * `at(beat)` returns null there. Each segment carries a confidence in [0, 1]:
+ * the fraction of the window weight explained by chord tones, reduced when the
+ * match is inexact, and duration-weighted across merged windows.
+ *
+ * Notes with a zero or negative duration never sound, so they are dropped at
+ * ingest: they contribute to neither the key inference, the span, nor any
+ * window's histogram.
+ *
+ * @param notes The notes to analyze (any number of tracks, flattened).
+ * @param opts Analysis options; see {@link ChordTimelineOptions}.
+ * @returns The inferred timeline, the key used, and per-segment confidences.
+ * @throws If `harmonicRhythm` is not positive.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 }, // C
+ *   { pitch: 64, startBeat: 0, durationBeat: 2 }, // E
+ *   { pitch: 67, startBeat: 0, durationBeat: 2 }, // G
+ * ];
+ * const { timeline, key } = chordTimelineFromNotes(notes);
+ * timeline.at(0); // the chord inferred over beat 0, or null
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function chordTimelineFromNotes(notes: NoteEvent[], opts?: ChordTimelineOptions): ChordTimelineResult;
+/**
+ * A cadence found between two consecutive timeline segments.
+ *
+ * @category Arrangement & Analysis
+ */
+type CadenceHit = {
+    /** The beat where the cadence arrives (the second chord's onset). */
+    atBeat: number;
+    type: Exclude<Cadence, null>;
+    from: Chord;
+    to: Chord;
+};
+/**
+ * Find cadences between consecutive segments of a chord timeline.
+ *
+ * Each temporally adjacent segment pair is classified with
+ * {@link detectCadence}; pairs forming no cadence are skipped. Segments
+ * separated by a gap (a rest in the timeline) are not a chord-to-chord
+ * progression, so they are never paired.
+ *
+ * @param timeline The chord timeline to scan.
+ * @param key The prevailing key.
+ * @returns The cadences found, in time order.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes, detectCadences } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 67, startBeat: 0, durationBeat: 4 }, // G, a dominant
+ *   { pitch: 60, startBeat: 4, durationBeat: 4 }, // C, the tonic
+ * ];
+ * const { timeline, key } = chordTimelineFromNotes(notes);
+ * const cadences = detectCadences(timeline, key);
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceHit[];
+
+export { type CadenceHit as C, type ChordSegment as a, type ChordTimeline as b, type ChordTimelineOptions as c, type ChordTimelineResult as d, chordTimelineFromChords as e, chordTimelineFromNotes as f, detectCadences as g };