@libraz/libcantus 0.9.2 → 0.9.4

package/dist/styled-BjXtOFNk.d.cts

@@ -1,282 +0,0 @@
-import { C as Chord } from './index-BOBXBNwP.cjs';
-
-/**
- * Test whether every chord pitch class is contained in a scale.
- *
- * @param chordPcs The chord's pitch classes (0..11).
- * @param scaleMask The scale's 12-bit mode mask.
- * @param scaleRootPc The pitch class the mask is rooted on.
- * @returns True if the scale is a superset of the chord.
- *
- * @category Scales
- */
-declare function scaleMatchesChord(chordPcs: number[], scaleMask: number, scaleRootPc: number): boolean;
-/**
- * A named scale rooted on a pitch class that fits over a chord.
- *
- * @category Scales
- */
-type ChordScaleMatch = {
-    name: string;
-    rootPc: number;
-};
-/**
- * List the scales that fit over a chord, best fit first.
- *
- * Only the chord root is considered as the scale root, matching the
- * conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
- * whose pitch-class set is a superset of the chord's is returned once per
- * distinct pitch-class set (aliased masks such as major/ionian report only the
- * modal name), ranked by fewest extra scale tones beyond the chord, then by
- * scale size (heptatonic before larger scales), then by scale name. For bare
- * triads and smaller chords, heptatonic scales rank before pentatonics and
- * other sizes: a pentatonic adds no modal color over a triad, so the seven-note
- * modes are the more useful answer. The chromatic scale is only returned as a
- * fallback when no other scale contains the chord.
- *
- * @param chord The chord to fit scales over.
- * @returns The matching scales rooted on the chord root, best fit first.
- *
- * @example
- * ```ts
- * import { makeChord, chordScales } from '@libraz/libcantus';
- * const scales = chordScales(makeChord(0, 'maj7'));
- * // scales for Cmaj7, best fit first; each is { name, rootPc: 0 }
- * ```
- *
- * @category Scales
- */
-declare function chordScales(chord: Chord): ChordScaleMatch[];
-/**
- * List a scale's avoid notes over a chord.
- *
- * An avoid note is a non-chord scale tone that lies a semitone directly above a
- * chord tone; sounding it against the chord clashes. The scale is rooted on the
- * chord root. If the scale does not contain the chord, no avoid notes exist.
- *
- * @param chord The chord providing the chord tones.
- * @param scaleName A key of {@link NAMED_SCALES}.
- * @returns The avoid-note pitch classes, sorted ascending in [0, 11].
- *
- * @category Scales
- */
-declare function avoidNotes(chord: Chord, scaleName: string): number[];
-/**
- * List a scale's available tensions over a chord.
- *
- * Available tensions are scale tones that are neither chord tones nor avoid
- * notes, i.e. the usable color tones (typically the 9/11/13 region). The scale
- * is rooted on the chord root. If the scale does not contain the chord, there
- * are no available tensions.
- *
- * @param chord The chord providing the chord tones.
- * @param scaleName A key of {@link NAMED_SCALES}.
- * @returns The available-tension pitch classes, sorted ascending in [0, 11].
- *
- * @example
- * ```ts
- * import { makeChord, availableTensions } from '@libraz/libcantus';
- * availableTensions(makeChord(0, 'maj7'), 'ionian'); // [2, 9] — color tones over Cmaj7
- * ```
- *
- * @category Scales
- */
-declare function availableTensions(chord: Chord, scaleName: string): number[];
-/**
- * A scale fit over a chord together with its avoid notes and tensions.
- *
- * @category Scales
- */
-type ChordScaleReportEntry = {
-    name: string;
-    rootPc: number;
-    avoid: number[];
-    tensions: number[];
-};
-/**
- * Report the best-fitting scales for a chord with their avoid notes and tensions.
- *
- * Combines {@link chordScales}, {@link avoidNotes}, and {@link availableTensions}
- * into a single ergonomic result, ordered best fit first.
- *
- * @param chord The chord to analyze.
- * @param limit Optional maximum number of scales to report; all by default.
- * @returns One entry per reported scale, best fit first.
- *
- * @category Scales
- */
-declare function chordScaleReport(chord: Chord, limit?: number): ChordScaleReportEntry[];
-/**
- * A chord paired with the scale chosen for it by {@link scalesForChanges}.
- *
- * @category Scales
- */
-type ScaleChoice = {
-    chord: Chord;
-    scale: ChordScaleMatch;
-};
-/**
- * Choose one scale per chord across a progression, favoring continuity.
- *
- * Each chord's {@link chordScales} candidates form a stage in a Viterbi-style
- * dynamic program. The transition cost between adjacent choices is the number
- * of pitch classes that differ between their pitch-class sets (the symmetric
- * difference), plus a small penalty for straying from a chord's best-fit scale
- * so that ties break toward the tighter fit. The minimum-total-cost path is
- * returned, one {@link ScaleChoice} per input chord in the original order.
- *
- * @param chords The chord sequence to choose scales for.
- * @returns One scale choice per chord, in input order.
- *
- * @category Scales
- */
-declare function scalesForChanges(chords: Chord[]): ScaleChoice[];
-
-/**
- * An inclusive MIDI pitch range for a single voice.
- *
- * @category Voicing & Counterpoint
- */
-type VoiceRange = {
-    min: number;
-    max: number;
-};
-/**
- * Default four-voice SATB ranges, ascending (index 0 = lowest):
- * bass E2–C4 (40–60), tenor C3–G4 (48–67), alto G3–D5 (55–74),
- * soprano C4–G5 (60–79).
- *
- * @category Voicing & Counterpoint
- */
-declare const SATB_RANGES: readonly VoiceRange[];
-/**
- * Options controlling {@link voiceChord} and {@link voiceProgression}.
- *
- * @category Voicing & Counterpoint
- */
-type VoicingOptions = {
-    /**
-     * Number of voices to realize. Ignored when `ranges` is given.
-     *
-     * @defaultValue 4
-     */
-    voices?: number;
-    /** Explicit per-voice ranges, ascending (index 0 = lowest). Takes precedence over `voices`. */
-    ranges?: VoiceRange[];
-    /**
-     * Maximum spacing in semitones between adjacent upper voices.
-     *
-     * @defaultValue 12
-     */
-    maxSpacing?: number;
-};
-/**
- * Realize a single chord as one MIDI pitch per voice, ascending (index 0 =
- * lowest). The bass voice takes the chord's `bassPc` when set, otherwise the
- * root; upper voices take chord pitch classes, doubling the root or fifth as
- * needed to fill all voices. The result stays inside each voice's range, keeps
- * adjacent upper voices within `maxSpacing`, avoids voice crossing, and is
- * deterministic: a compact close-position voicing centered in the ranges.
- *
- * @param chord The chord to voice.
- * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
- * @returns MIDI pitches, ascending, one per voice.
- * @throws If no voicing fits the given ranges.
- * @example
- * ```ts
- * import { parseChordSymbol, voiceChord } from '@libraz/libcantus';
- * const chord = parseChordSymbol('Cmaj7');
- * voiceChord(chord); // four ascending MIDI pitches within the SATB ranges
- * ```
- * @category Voicing & Counterpoint
- */
-declare function voiceChord(chord: Chord, opts?: VoicingOptions): number[];
-/**
- * Voice a chord progression with smooth voice leading. The first chord is
- * voiced with {@link voiceChord}; each subsequent chord picks, from a bounded
- * deterministic candidate set, the voicing minimizing the voice-leading cost
- * from the previous voicing plus a large penalty per counterpoint violation
- * (parallel perfects/octaves, voice crossing, voice overlap, and over-wide
- * upper-voice spacing).
- *
- * @param chords The chords to voice in order.
- * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
- * @returns One voicing per chord, each ascending with one MIDI pitch per voice.
- * @throws If any chord admits no voicing within the given ranges.
- * @example
- * ```ts
- * import { parseChordSymbol, voiceProgression } from '@libraz/libcantus';
- * const chords = ['C', 'Am', 'F', 'G'].map((s) => parseChordSymbol(s));
- * voiceProgression(chords); // one four-voice voicing per chord, smoothly led
- * ```
- * @category Voicing & Counterpoint
- */
-declare function voiceProgression(chords: Chord[], opts?: VoicingOptions): number[][];
-
-/**
- * A tertian voicing style for {@link voiceChordStyled}.
- *
- * - `close`: the plain close-position tertian stack.
- * - `drop2`: the second voice from the top dropped an octave (drop-2 voicing).
- * - `drop3`: the third voice from the top dropped an octave (drop-3 voicing).
- * - `shell`: root plus guide tones (third and seventh) for seventh chords, or
- *   root/third/fifth for triads; the fifth and tensions are omitted.
- * - `rootless`: the root omitted, keeping third/fifth/seventh and tensions
- *   (a typical left-hand jazz voicing).
- *
- * @category Voicing & Counterpoint
- */
-type VoicingStyle = 'close' | 'drop2' | 'drop3' | 'shell' | 'rootless';
-/**
- * Options controlling {@link voiceChordStyled}.
- *
- * @category Voicing & Counterpoint
- */
-type StyledVoicingOptions = {
-    /**
-     * Voicing style to build.
-     *
-     * @defaultValue 'close'
-     */
-    style?: VoicingStyle;
-    /** Constrain the highest voice to this pitch class (0..11) when given. */
-    topNote?: number;
-    /**
-     * Base octave for the close stack; the stack begins near `12 * octave`.
-     *
-     * @defaultValue 4
-     */
-    octave?: number;
-    /**
-     * Omit the root regardless of style (relevant for jazz voicings).
-     *
-     * @defaultValue false
-     */
-    rootless?: boolean;
-};
-/**
- * Realize a single chord as an explicit tertian voicing in a chosen style,
- * independent of the SATB range search used by {@link voiceChord}.
- *
- * The chord tones are stacked in close position from the bass (`bassPc`, else
- * `rootPc`) in the given scientific-pitch `octave` upward (octave 4 starts the
- * bass near C4 = MIDI 60, matching {@link midiToNote} and the bass module).
- * When `topNote` is given the stack is rotated so the highest voice's pitch
- * class equals that note (or the nearest chord tone). The chosen
- * {@link VoicingStyle} then transforms the stack, and the result is returned as
- * ascending MIDI pitches (index 0 = lowest).
- *
- * @param chord The chord to voice.
- * @param opts Styled voicing options; defaults to a close voicing at octave 4.
- * @returns MIDI pitches, ascending, one per retained voice.
- * @example
- * ```ts
- * import { parseChordSymbol, voiceChordStyled } from '@libraz/libcantus';
- * const chord = parseChordSymbol('Dm7');
- * voiceChordStyled(chord, { style: 'drop2' }); // ascending MIDI pitches, drop-2 voicing
- * ```
- * @category Voicing & Counterpoint
- */
-declare function voiceChordStyled(chord: Chord, opts?: StyledVoicingOptions): number[];
-
-export { type ChordScaleMatch as C, SATB_RANGES as S, type VoiceRange as V, type ChordScaleReportEntry as a, type ScaleChoice as b, type StyledVoicingOptions as c, type VoicingOptions as d, type VoicingStyle as e, availableTensions as f, avoidNotes as g, chordScaleReport as h, chordScales as i, scalesForChanges as j, voiceChordStyled as k, voiceProgression as l, scaleMatchesChord as s, voiceChord as v };

package/dist/styled-D7BAx3S3.d.ts

@@ -1,282 +0,0 @@
-import { C as Chord } from './index-CM5W4rcm.js';
-
-/**
- * Test whether every chord pitch class is contained in a scale.
- *
- * @param chordPcs The chord's pitch classes (0..11).
- * @param scaleMask The scale's 12-bit mode mask.
- * @param scaleRootPc The pitch class the mask is rooted on.
- * @returns True if the scale is a superset of the chord.
- *
- * @category Scales
- */
-declare function scaleMatchesChord(chordPcs: number[], scaleMask: number, scaleRootPc: number): boolean;
-/**
- * A named scale rooted on a pitch class that fits over a chord.
- *
- * @category Scales
- */
-type ChordScaleMatch = {
-    name: string;
-    rootPc: number;
-};
-/**
- * List the scales that fit over a chord, best fit first.
- *
- * Only the chord root is considered as the scale root, matching the
- * conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
- * whose pitch-class set is a superset of the chord's is returned once per
- * distinct pitch-class set (aliased masks such as major/ionian report only the
- * modal name), ranked by fewest extra scale tones beyond the chord, then by
- * scale size (heptatonic before larger scales), then by scale name. For bare
- * triads and smaller chords, heptatonic scales rank before pentatonics and
- * other sizes: a pentatonic adds no modal color over a triad, so the seven-note
- * modes are the more useful answer. The chromatic scale is only returned as a
- * fallback when no other scale contains the chord.
- *
- * @param chord The chord to fit scales over.
- * @returns The matching scales rooted on the chord root, best fit first.
- *
- * @example
- * ```ts
- * import { makeChord, chordScales } from '@libraz/libcantus';
- * const scales = chordScales(makeChord(0, 'maj7'));
- * // scales for Cmaj7, best fit first; each is { name, rootPc: 0 }
- * ```
- *
- * @category Scales
- */
-declare function chordScales(chord: Chord): ChordScaleMatch[];
-/**
- * List a scale's avoid notes over a chord.
- *
- * An avoid note is a non-chord scale tone that lies a semitone directly above a
- * chord tone; sounding it against the chord clashes. The scale is rooted on the
- * chord root. If the scale does not contain the chord, no avoid notes exist.
- *
- * @param chord The chord providing the chord tones.
- * @param scaleName A key of {@link NAMED_SCALES}.
- * @returns The avoid-note pitch classes, sorted ascending in [0, 11].
- *
- * @category Scales
- */
-declare function avoidNotes(chord: Chord, scaleName: string): number[];
-/**
- * List a scale's available tensions over a chord.
- *
- * Available tensions are scale tones that are neither chord tones nor avoid
- * notes, i.e. the usable color tones (typically the 9/11/13 region). The scale
- * is rooted on the chord root. If the scale does not contain the chord, there
- * are no available tensions.
- *
- * @param chord The chord providing the chord tones.
- * @param scaleName A key of {@link NAMED_SCALES}.
- * @returns The available-tension pitch classes, sorted ascending in [0, 11].
- *
- * @example
- * ```ts
- * import { makeChord, availableTensions } from '@libraz/libcantus';
- * availableTensions(makeChord(0, 'maj7'), 'ionian'); // [2, 9] — color tones over Cmaj7
- * ```
- *
- * @category Scales
- */
-declare function availableTensions(chord: Chord, scaleName: string): number[];
-/**
- * A scale fit over a chord together with its avoid notes and tensions.
- *
- * @category Scales
- */
-type ChordScaleReportEntry = {
-    name: string;
-    rootPc: number;
-    avoid: number[];
-    tensions: number[];
-};
-/**
- * Report the best-fitting scales for a chord with their avoid notes and tensions.
- *
- * Combines {@link chordScales}, {@link avoidNotes}, and {@link availableTensions}
- * into a single ergonomic result, ordered best fit first.
- *
- * @param chord The chord to analyze.
- * @param limit Optional maximum number of scales to report; all by default.
- * @returns One entry per reported scale, best fit first.
- *
- * @category Scales
- */
-declare function chordScaleReport(chord: Chord, limit?: number): ChordScaleReportEntry[];
-/**
- * A chord paired with the scale chosen for it by {@link scalesForChanges}.
- *
- * @category Scales
- */
-type ScaleChoice = {
-    chord: Chord;
-    scale: ChordScaleMatch;
-};
-/**
- * Choose one scale per chord across a progression, favoring continuity.
- *
- * Each chord's {@link chordScales} candidates form a stage in a Viterbi-style
- * dynamic program. The transition cost between adjacent choices is the number
- * of pitch classes that differ between their pitch-class sets (the symmetric
- * difference), plus a small penalty for straying from a chord's best-fit scale
- * so that ties break toward the tighter fit. The minimum-total-cost path is
- * returned, one {@link ScaleChoice} per input chord in the original order.
- *
- * @param chords The chord sequence to choose scales for.
- * @returns One scale choice per chord, in input order.
- *
- * @category Scales
- */
-declare function scalesForChanges(chords: Chord[]): ScaleChoice[];
-
-/**
- * An inclusive MIDI pitch range for a single voice.
- *
- * @category Voicing & Counterpoint
- */
-type VoiceRange = {
-    min: number;
-    max: number;
-};
-/**
- * Default four-voice SATB ranges, ascending (index 0 = lowest):
- * bass E2–C4 (40–60), tenor C3–G4 (48–67), alto G3–D5 (55–74),
- * soprano C4–G5 (60–79).
- *
- * @category Voicing & Counterpoint
- */
-declare const SATB_RANGES: readonly VoiceRange[];
-/**
- * Options controlling {@link voiceChord} and {@link voiceProgression}.
- *
- * @category Voicing & Counterpoint
- */
-type VoicingOptions = {
-    /**
-     * Number of voices to realize. Ignored when `ranges` is given.
-     *
-     * @defaultValue 4
-     */
-    voices?: number;
-    /** Explicit per-voice ranges, ascending (index 0 = lowest). Takes precedence over `voices`. */
-    ranges?: VoiceRange[];
-    /**
-     * Maximum spacing in semitones between adjacent upper voices.
-     *
-     * @defaultValue 12
-     */
-    maxSpacing?: number;
-};
-/**
- * Realize a single chord as one MIDI pitch per voice, ascending (index 0 =
- * lowest). The bass voice takes the chord's `bassPc` when set, otherwise the
- * root; upper voices take chord pitch classes, doubling the root or fifth as
- * needed to fill all voices. The result stays inside each voice's range, keeps
- * adjacent upper voices within `maxSpacing`, avoids voice crossing, and is
- * deterministic: a compact close-position voicing centered in the ranges.
- *
- * @param chord The chord to voice.
- * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
- * @returns MIDI pitches, ascending, one per voice.
- * @throws If no voicing fits the given ranges.
- * @example
- * ```ts
- * import { parseChordSymbol, voiceChord } from '@libraz/libcantus';
- * const chord = parseChordSymbol('Cmaj7');
- * voiceChord(chord); // four ascending MIDI pitches within the SATB ranges
- * ```
- * @category Voicing & Counterpoint
- */
-declare function voiceChord(chord: Chord, opts?: VoicingOptions): number[];
-/**
- * Voice a chord progression with smooth voice leading. The first chord is
- * voiced with {@link voiceChord}; each subsequent chord picks, from a bounded
- * deterministic candidate set, the voicing minimizing the voice-leading cost
- * from the previous voicing plus a large penalty per counterpoint violation
- * (parallel perfects/octaves, voice crossing, voice overlap, and over-wide
- * upper-voice spacing).
- *
- * @param chords The chords to voice in order.
- * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
- * @returns One voicing per chord, each ascending with one MIDI pitch per voice.
- * @throws If any chord admits no voicing within the given ranges.
- * @example
- * ```ts
- * import { parseChordSymbol, voiceProgression } from '@libraz/libcantus';
- * const chords = ['C', 'Am', 'F', 'G'].map((s) => parseChordSymbol(s));
- * voiceProgression(chords); // one four-voice voicing per chord, smoothly led
- * ```
- * @category Voicing & Counterpoint
- */
-declare function voiceProgression(chords: Chord[], opts?: VoicingOptions): number[][];
-
-/**
- * A tertian voicing style for {@link voiceChordStyled}.
- *
- * - `close`: the plain close-position tertian stack.
- * - `drop2`: the second voice from the top dropped an octave (drop-2 voicing).
- * - `drop3`: the third voice from the top dropped an octave (drop-3 voicing).
- * - `shell`: root plus guide tones (third and seventh) for seventh chords, or
- *   root/third/fifth for triads; the fifth and tensions are omitted.
- * - `rootless`: the root omitted, keeping third/fifth/seventh and tensions
- *   (a typical left-hand jazz voicing).
- *
- * @category Voicing & Counterpoint
- */
-type VoicingStyle = 'close' | 'drop2' | 'drop3' | 'shell' | 'rootless';
-/**
- * Options controlling {@link voiceChordStyled}.
- *
- * @category Voicing & Counterpoint
- */
-type StyledVoicingOptions = {
-    /**
-     * Voicing style to build.
-     *
-     * @defaultValue 'close'
-     */
-    style?: VoicingStyle;
-    /** Constrain the highest voice to this pitch class (0..11) when given. */
-    topNote?: number;
-    /**
-     * Base octave for the close stack; the stack begins near `12 * octave`.
-     *
-     * @defaultValue 4
-     */
-    octave?: number;
-    /**
-     * Omit the root regardless of style (relevant for jazz voicings).
-     *
-     * @defaultValue false
-     */
-    rootless?: boolean;
-};
-/**
- * Realize a single chord as an explicit tertian voicing in a chosen style,
- * independent of the SATB range search used by {@link voiceChord}.
- *
- * The chord tones are stacked in close position from the bass (`bassPc`, else
- * `rootPc`) in the given scientific-pitch `octave` upward (octave 4 starts the
- * bass near C4 = MIDI 60, matching {@link midiToNote} and the bass module).
- * When `topNote` is given the stack is rotated so the highest voice's pitch
- * class equals that note (or the nearest chord tone). The chosen
- * {@link VoicingStyle} then transforms the stack, and the result is returned as
- * ascending MIDI pitches (index 0 = lowest).
- *
- * @param chord The chord to voice.
- * @param opts Styled voicing options; defaults to a close voicing at octave 4.
- * @returns MIDI pitches, ascending, one per retained voice.
- * @example
- * ```ts
- * import { parseChordSymbol, voiceChordStyled } from '@libraz/libcantus';
- * const chord = parseChordSymbol('Dm7');
- * voiceChordStyled(chord, { style: 'drop2' }); // ascending MIDI pitches, drop-2 voicing
- * ```
- * @category Voicing & Counterpoint
- */
-declare function voiceChordStyled(chord: Chord, opts?: StyledVoicingOptions): number[];
-
-export { type ChordScaleMatch as C, SATB_RANGES as S, type VoiceRange as V, type ChordScaleReportEntry as a, type ScaleChoice as b, type StyledVoicingOptions as c, type VoicingOptions as d, type VoicingStyle as e, availableTensions as f, avoidNotes as g, chordScaleReport as h, chordScales as i, scalesForChanges as j, voiceChordStyled as k, voiceProgression as l, scaleMatchesChord as s, voiceChord as v };

package/src/analyze/arrange/index.ts

@@ -1,21 +0,0 @@
-/**
- * Arrangement analysis: the capstone that ties the timeline, per-voice analysis,
- * functional harmony, and safety modules together for a whole multi-track piece.
- *
- * A chord timeline and key are inferred once from every track's notes pooled
- * together; each track is then analysed against that shared harmony, notes that
- * clash with the sounding chord are collected as conflicts, and a coarse tension
- * curve is sampled across the piece.
- */
-
-export type { TensionPoint } from './tension.js';
-export { tensionCurve } from './tension.js';
-export type {
-  ArrangementAnalysis,
-  ArrangementOptions,
-  ArrangementTrack,
-  Conflict,
-  TrackAnalysis,
-  TrackRole,
-} from './tracks.js';
-export { analyzeArrangement } from './tracks.js';