@libraz/libcantus 0.9.4 → 1.0.0

package/dist/index-C83mZI1P.d.ts

@@ -1,242 +0,0 @@
-import { K as KeyScale } from './types-BN6_Q9Kl.js';
-
-/**
- * Chord quality identifiers understood by the chord builder.
- *
- * @category Chords
- */
-type ChordQuality = 'maj' | 'min' | 'dim' | 'aug' | 'maj7' | 'min7' | 'dom7' | 'dim7' | 'm7b5' | 'minMaj7' | 'aug7' | 'augMaj7' | 'majb5' | '6' | 'min6' | '6/9' | 'sus2' | 'sus4' | 'add9' | 'add11' | 'maj9' | 'min9' | 'dom9' | '7b9' | '7#9' | '7#11' | '7b13' | '11' | '13' | '5' | '7sus4' | '7b5' | '7alt' | '13b9' | 'maj13' | 'maj7#11' | 'min11' | 'min13' | 'minAdd9' | 'min6/9';
-/**
- * The basic role a chord tone plays: the degrees a chord's own template names.
- *
- * The shared vocabulary behind {@link chordToneRole}, the harmony layer's
- * `HarmonyRole`, and the voice analyser's labels, so the three cannot drift.
- *
- * @category Chords
- */
-type ChordToneRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
-/**
- * A bare spelled pitch used as an enharmonic hint: a diatonic letter
- * (0..6 = C..B) plus a chromatic alteration (-2 double-flat .. +2 double-sharp).
- * Mirrors the letter/alter half of the pitch module's `Note` without an octave.
- *
- * @category Chords
- */
-type PitchSpelling = {
-    letter: number;
-    alter: number;
-};
-/**
- * A chord expressed as a root pitch class plus semitone offsets.
- *
- * `rootSpelling`/`bassSpelling` are optional enharmonic hints recorded by
- * parsers (e.g. `parseChordSymbol('Bb7')`) so formatters can reproduce the
- * original spelling instead of defaulting to sharps. Consumers may ignore
- * them; a hint is only trusted when its pitch class still matches the
- * corresponding `rootPc`/`bassPc`.
- *
- * @category Chords
- */
-type Chord = {
-    rootPc: number;
-    quality: ChordQuality;
-    intervals: number[];
-    bassPc?: number;
-    rootSpelling?: PitchSpelling;
-    bassSpelling?: PitchSpelling;
-};
-/**
- * A chord positioned in time: a root pitch class and quality placed at a beat,
- * with optional harmonic-analysis hints. Serves as the neutral exchange record
- * between progression generators and timeline analysers.
- *
- * @category Composition
- */
-type ChordSpan = {
-    rootPc: number;
-    quality: ChordQuality;
-    startBeat: number;
-    bassPc?: number;
-    /** 0-based scale degree of the chord root, when known. */
-    degree?: number;
-    /** True when the chord is a secondary dominant tonicizing another degree. */
-    secondaryDominant?: boolean;
-};
-/**
- * A chord occupying a half-open beat span `[startBeat, endBeat)`.
- *
- * The exchange record between anything that lays chords out in time — a
- * timeline analysis, a bass-line plan, an accompaniment generator — so those
- * surfaces share one definition instead of agreeing by coincidence.
- *
- * @category Composition
- */
-type ChordSegment = {
-    startBeat: number;
-    endBeat: number;
-    chord: Chord;
-};
-/**
- * All chord qualities the builder understands, in declaration order.
- *
- * The order is stable but carries no meaning: it is neither alphabetical nor
- * sorted by template size. {@link detectChord} uses it as its final tie-break,
- * so it is part of the observable behaviour and does not get reshuffled
- * casually — but do not read it as a ranking.
- *
- * @category Chords
- */
-declare function chordQualities(): ChordQuality[];
-/**
- * Build a chord rooted on a diatonic scale degree.
- *
- * The root pitch class is the degree's diatonic pitch class in `key`; the
- * quality's interval template is attached unchanged. Degrees beyond the scale
- * length wrap around.
- *
- * @param degree 0-based scale degree of the chord root.
- * @param ext Chord quality to apply.
- * @param key Key context supplying the diatonic root.
- * @returns The constructed chord.
- *
- * @category Chords
- */
-declare function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale): Chord;
-/**
- * Build a chord from an explicit root pitch class and quality.
- *
- * @param rootPc Root pitch class (0..11).
- * @param quality Chord quality supplying the interval template.
- * @param bassPc Optional slash-chord bass pitch class.
- * @returns The constructed chord.
- *
- * @example
- * ```ts
- * import { makeChord } from '@libraz/libcantus';
- * const cmaj7 = makeChord(0, 'maj7');
- * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
- * ```
- *
- * @category Chords
- */
-declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord;
-/**
- * Transpose a chord by a number of semitones.
- *
- * The interval template is carried over untouched, so a chord whose intervals
- * were customised keeps them, and a slash bass moves with the root. Enharmonic
- * spelling hints are dropped rather than shifted: the letter a transposed root
- * should take depends on the destination key, which a semitone count does not
- * carry. Pass the result through {@link spellChord} to respell it.
- *
- * @param chord The chord to transpose.
- * @param semitones The signed semitone offset.
- * @returns The transposed chord.
- * @throws If `semitones` is not finite.
- *
- * @example
- * ```ts
- * import { formatChordSymbol, parseChordSymbol, transposeChord } from '@libraz/libcantus';
- * formatChordSymbol(transposeChord(parseChordSymbol('C/G'), 2)); // 'D/A'
- * ```
- *
- * @category Chords
- */
-declare function transposeChord(chord: Chord, semitones: number): Chord;
-/**
- * Get the sorted, deduplicated pitch classes of a chord.
- *
- * A slash bass is one of them: `F/G` sounds a G, the voicers put it in the
- * bass, and a set that omitted it would not re-detect as the chord it came
- * from. Pass `includeBass: false` to enumerate the interval template alone.
- *
- * @param chord The chord to enumerate.
- * @param opts Set `includeBass: false` to omit a slash bass.
- * @returns The chord's pitch classes, sorted ascending in [0, 11].
- *
- * @example
- * ```ts
- * import { makeChord, chordPitchClasses } from '@libraz/libcantus';
- * chordPitchClasses(makeChord(0, 'maj7')); // [0, 4, 7, 11]
- * chordPitchClasses(makeChord(5, 'maj', 7)); // [0, 5, 7, 9] — F/G, G included
- * ```
- *
- * @category Chords
- */
-declare function chordPitchClasses(chord: Chord, opts?: {
-    includeBass?: boolean;
-}): number[];
-/**
- * A pitch's interval class above the chord root, in [0, 11].
- *
- * The shared reading of "where does this pitch sit in the chord", used by the
- * safety evaluator and the voice analyser alike so they cannot disagree.
- *
- * @param pitch MIDI pitch or bare pitch class.
- * @param chord The chord providing the root reference.
- * @returns The interval class above the root.
- * @category Chords
- */
-declare function intervalAboveRoot(pitch: number, chord: Chord): number;
-/**
- * Whether a pitch is one of a chord's tones, ignoring octave.
- *
- * @param pitch MIDI pitch or bare pitch class.
- * @param chord The chord, or null for no sounding harmony.
- * @returns True when the pitch class belongs to the chord.
- * @category Chords
- */
-declare function isChordMember(pitch: number, chord: Chord | null): boolean;
-/**
- * Determine a pitch's harmonic role within a chord.
- *
- * The role is derived from the pitch's interval above the chord root, reduced
- * modulo 12. A major sixth (9) reads as a `sixth` for sixth chords but as a
- * `seventh` for a diminished-seventh chord; ninths and other tensions have no
- * basic role and return null.
- *
- * @param pitch MIDI pitch or bare pitch class.
- * @param chord The chord providing the root reference.
- * @returns The chord-tone role, or null if the pitch has no basic role.
- *
- * @category Chords
- */
-declare function chordToneRole(pitch: number, chord: Chord): ChordToneRole | null;
-/**
- * Build the diatonic triad rooted on a scale degree by stacking scale thirds.
- *
- * Unlike {@link chordFromDegree}, the chord quality is derived from the scale
- * rather than supplied, so degrees yield their scale-correct triads (e.g. a
- * diminished triad on the leading tone of a major key).
- *
- * @param degree 0-based scale degree of the chord root.
- * @param key Key/scale context.
- * @returns The diatonic triad.
- * @throws If the scale is not heptatonic. Stacking thirds means skipping every
- *   other degree, which only lands on a triad when there are seven of them, so
- *   the pentatonic, blues, whole-tone, octatonic and chromatic scales have no
- *   diatonic triad; use {@link chordFromDegree} with an explicit quality there.
- *
- * @example
- * ```ts
- * import { majorKey, diatonicTriad } from '@libraz/libcantus';
- * const tonic = diatonicTriad(0, majorKey(0)); // C major triad (degree 0 of C major)
- * ```
- *
- * @category Chords
- */
-declare function diatonicTriad(degree: number, key: KeyScale): Chord;
-/**
- * Build the diatonic seventh chord rooted on a scale degree.
- *
- * @param degree 0-based scale degree of the chord root.
- * @param key Key/scale context.
- * @returns The diatonic seventh chord.
- * @throws If the scale is not heptatonic, for the reason given on
- *   {@link diatonicTriad}.
- *
- * @category Chords
- */
-declare function diatonicSeventh(degree: number, key: KeyScale): Chord;
-
-export { type Chord as C, type PitchSpelling as P, type ChordQuality as a, type ChordSegment as b, type ChordSpan as c, type ChordToneRole as d, chordFromDegree as e, chordPitchClasses as f, chordQualities as g, chordToneRole as h, diatonicSeventh as i, diatonicTriad as j, intervalAboveRoot as k, isChordMember as l, makeChord as m, transposeChord as t };

package/dist/index-DXd9JikN.d.cts

@@ -1,246 +0,0 @@
-/**
- * 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.
- *
- * @category Rhythm & Meter
- */
-type TimeSignature = {
-    numerator: number;
-    denominator: number;
-    /**
-     * Optional additive grouping of the bar's main pulses, as the felt-beat
-     * lengths in pulses — e.g. `[2, 2, 3]` for a 2+2+3 reading of 7/8, or
-     * `[3, 2]` for 5/8. The entries must be positive integers summing to the
-     * numerator.
-     *
-     * A compound numerator accepts both readings. 9/8 groups its three dotted
-     * pulses as `[1, 1, 1]`, or reads additively as `[2, 2, 2, 3]` quavers; a
-     * grouping that sums to the numerator selects the additive reading, so
-     * aksak and other additive metres are expressible. {@link pulsesPerBar}
-     * and {@link isCompound} follow whichever reading the grouping selects.
-     *
-     * When present, the head pulse of each group (other than the downbeat) is
-     * treated as a secondary strong pulse by
-     * {@link metricWeight}/{@link isStrongBeat}; when absent, all main pulses
-     * are weighted equally as flat, evenly divided pulses.
-     */
-    grouping?: number[];
-};
-/**
- * A position expressed as a bar index and a quarter-note offset within the bar.
- *
- * @category Rhythm & Meter
- */
-type BarPosition = {
-    /** 0-based bar index. {@link formatBarPosition} renders it 1-based. */
-    bar: number;
-    /**
-     * Quarter-note offset from the start of the bar — not the felt beat. In 6/8
-     * the second felt beat is at `beat: 1.5`; {@link barPositionToPulse} converts
-     * to felt-beat numbering.
-     */
-    beat: number;
-};
-/**
- * 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.
- * @example
- * ```ts
- * import { parseTimeSignature } from '@libraz/libcantus';
- * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }
- * ```
- * @category Rhythm & Meter
- */
-declare function parseTimeSignature(text: string): TimeSignature;
-/**
- * Render a time signature as `"n/d"`, or as `"a+b+c/d"` when it carries an
- * additive grouping and `grouping` is requested.
- *
- * The plain form drops the grouping, so a round trip through it reads 7/8 as
- * flat rather than as 2+2+3; ask for the additive form to keep it.
- *
- * @param ts The time signature.
- * @param opts Set `grouping: true` to render an additive grouping.
- * @returns The formatted signature.
- * @example
- * ```ts
- * import { formatTimeSignature } from '@libraz/libcantus';
- * const aksak = { numerator: 7, denominator: 8, grouping: [2, 2, 3] };
- * formatTimeSignature(aksak); // '7/8'
- * formatTimeSignature(aksak, { grouping: true }); // '2+2+3/8'
- * ```
- * @category Rhythm & Meter
- */
-declare function formatTimeSignature(ts: TimeSignature, opts?: {
-    grouping?: boolean;
-}): string;
-/**
- * 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, and neither
- * is a signature whose {@link TimeSignature.grouping} selects the additive
- * reading (9/8 as 2+2+2+3).
- *
- * @param ts The time signature.
- * @returns True for compound meters.
- * @category Rhythm & Meter
- */
-declare function isCompound(ts: TimeSignature): boolean;
-/**
- * Length of a bar in quarter-note beats.
- *
- * @param ts The time signature.
- * @returns The bar length in quarter notes.
- * @category Rhythm & Meter
- */
-declare function beatsPerBar(ts: TimeSignature): number;
-/**
- * Number of main pulses (felt beats) per bar: the numerator for simple meters,
- * a third of it for compound meters.
- *
- * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses
- * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and
- * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set
- * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
- * group's head pulse.
- *
- * @param ts The time signature.
- * @returns The pulse count per bar.
- * @category Rhythm & Meter
- */
-declare function pulsesPerBar(ts: TimeSignature): number;
-/**
- * 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.
- * @example
- * ```ts
- * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';
- * const ts = parseTimeSignature('4/4');
- * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }
- * ```
- * @category Rhythm & Meter
- */
-declare function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition;
-/**
- * Length of one felt beat (main pulse) in quarter-note beats.
- *
- * A quarter note in simple meters, a dotted quarter in compound ones, and one
- * denominator unit in an additive metre. Position displays, click tracks, and
- * score export are all written against this length.
- *
- * @param ts The time signature.
- * @returns The pulse length in quarter-note beats.
- * @example
- * ```ts
- * import { parseTimeSignature, pulseBeats } from '@libraz/libcantus';
- * pulseBeats(parseTimeSignature('6/8')); // 1.5
- * ```
- * @category Rhythm & Meter
- */
-declare function pulseBeats(ts: TimeSignature): number;
-/**
- * The felt-beat number of a bar position, 1-based.
- *
- * {@link BarPosition.beat} is a quarter-note offset, so in 6/8 the second felt
- * beat reads as 1.5. This is the number a musician says and a position display
- * shows.
- *
- * @param pos The bar position.
- * @param ts The time signature.
- * @returns The 1-based felt-beat number, fractional between pulses.
- * @example
- * ```ts
- * import { barPositionToPulse, parseTimeSignature } from '@libraz/libcantus';
- * barPositionToPulse({ bar: 0, beat: 1.5 }, parseTimeSignature('6/8')); // 2
- * ```
- * @category Rhythm & Meter
- */
-declare function barPositionToPulse(pos: BarPosition, ts: TimeSignature): number;
-/**
- * Render an absolute position as the `bar.beat` a DAW or a score shows:
- * 1-based bar, 1-based felt beat.
- *
- * @param beatInQuarters Absolute position in quarter-note beats.
- * @param ts The time signature.
- * @param decimals Digits of the fractional beat to keep.
- * @returns The formatted position, e.g. `'3.2'` for bar 3, felt beat 2.
- * @example
- * ```ts
- * import { formatBarPosition, parseTimeSignature } from '@libraz/libcantus';
- * formatBarPosition(7.5, parseTimeSignature('6/8')); // '3.2'
- * ```
- * @category Rhythm & Meter
- */
-declare function formatBarPosition(beatInQuarters: number, ts: TimeSignature, decimals?: number): string;
-/**
- * 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.
- * @category Rhythm & Meter
- */
-declare function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number;
-/**
- * Metric weight of a position within its bar, on a 0–3 scale:
- * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an
- * off-pulse subdivision.
- *
- * The secondary strong pulse is the bar's midpoint in even simple/compound
- * meters. For an additive/irregular meter with {@link TimeSignature.grouping}
- * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the
- * downbeat is the secondary strong pulse instead; without a grouping every
- * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided
- * pulses).
- *
- * @param beatInQuarters Absolute or in-bar quarter-note position.
- * @param ts The time signature.
- * @returns The metric weight (0–3).
- * @throws If the time signature is malformed, including a grouping that is not
- *   a positive-integer list summing to the pulse count or the numerator.
- * @example
- * ```ts
- * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';
- * const ts = parseTimeSignature('4/4');
- * metricWeight(0, ts); // 3 (the downbeat)
- * ```
- * @category Rhythm & Meter
- */
-declare function metricWeight(beatInQuarters: number, ts: TimeSignature): number;
-/**
- * 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.
- * @category Rhythm & Meter
- */
-declare function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean;
-/**
- * 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.
- * @category Rhythm & Meter
- */
-declare function tuplet(totalBeats: number, count: number): number[];
-
-export { type BarPosition as B, type TimeSignature as T, barPositionToPulse as a, barPositionToBeat as b, beatToBarPosition as c, beatsPerBar as d, formatTimeSignature as e, formatBarPosition as f, isStrongBeat as g, pulseBeats as h, isCompound as i, pulsesPerBar as j, metricWeight as m, parseTimeSignature as p, tuplet as t };