@libraz/libcantus 0.9.4 → 1.0.0

package/dist/index-DXd9JikN.d.ts

@@ -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 };

package/dist/index-OG65ocOr.d.cts

@@ -1,272 +0,0 @@
-/**
- * Pitch spelling: letter-name notes, enharmonic-aware conversion, and spelled
- * intervals.
- *
- * The rest of the library works in pitch classes (0..11), which cannot tell a
- * G# from an Ab or an augmented fourth from a diminished fifth. This module adds
- * an explicit spelling layer — a note is a diatonic letter plus a chromatic
- * alteration — so interval quality (P/M/m/A/d) and enharmonic identity are
- * preserved.
- */
-/**
- * A spelled note: a diatonic letter, a chromatic alteration, and an optional
- * octave.
- *
- * - `letter` is 0..6 for C..B.
- * - `alter` is the number of semitones of alteration: -2 double-flat, -1 flat,
- *   0 natural, +1 sharp, +2 double-sharp.
- * - `octave` follows scientific pitch notation (middle C = C4 = MIDI 60). When
- *   absent, the note denotes a bare pitch class.
- *
- * @category Pitch & Intervals
- */
-type Note = {
-    letter: number;
-    alter: number;
-    octave?: number;
-};
-/**
- * The quality label of a spelled interval: perfect, major, minor, or one or
- * more augmentations or diminutions.
- *
- * This names how an interval is *spelled*. It is a different notion from
- * {@link ConsonanceClass}, which classifies how an interval *sounds* against
- * another voice.
- *
- * @see {@link ConsonanceClass}
- * @category Pitch & Intervals
- */
-type IntervalQualityLabel = 'P' | 'M' | 'm' | `A${string}` | `d${string}`;
-/**
- * A spelled interval: a diatonic number, a quality label, and its semitone span.
- *
- * @category Pitch & Intervals
- */
-type SpelledInterval = {
-    /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
-    number: number;
-    /** Quality label: 'P', 'M', 'm', or repeated 'A'/'d' for (multiply) aug/dim. */
-    quality: IntervalQualityLabel;
-    /** Signed semitone distance from the first note to the second. */
-    semitones: number;
-};
-/**
- * Reduce a MIDI pitch, a bare pitch class, or any signed offset to a pitch
- * class in [0, 11].
- *
- * This is the library's single definition of pitch-class arithmetic: every
- * layer routes through it so a fractional pitch reduces the same way
- * everywhere. A non-integral input is rounded to the nearest semitone first, so
- * a microtonal 60.6 reads as C# rather than C.
- *
- * @param value A MIDI pitch, pitch class, or signed semitone offset.
- * @returns The pitch class in [0, 11].
- * @example
- * ```ts
- * import { pitchClassOf } from '@libraz/libcantus';
- * pitchClassOf(61); // 1
- * pitchClassOf(-1); // 11
- * pitchClassOf(60.6); // 1
- * ```
- * @category Pitch & Intervals
- */
-declare function pitchClassOf(value: number): number;
-/**
- * Reduce a letter number or letter offset to a diatonic letter in [0, 6]
- * (0 = C .. 6 = B).
- *
- * @param value A letter number or signed letter offset.
- * @returns The diatonic letter in [0, 6].
- * @category Pitch & Intervals
- */
-declare function diatonicLetterOf(value: number): number;
-/**
- * The pitch class of a diatonic letter with no accidental (C = 0, D = 2, ...).
- *
- * @param letter A letter number or signed letter offset; reduced to [0, 6].
- * @returns The natural pitch class of that letter.
- * @category Pitch & Intervals
- */
-declare function naturalPitchClassOf(letter: number): number;
-/**
- * Parse scientific pitch notation into a {@link Note}.
- *
- * Accepts a letter (case-insensitive) followed by any number of same-direction
- * accidentals and an optional octave, e.g. `"C"`, `"C#4"`, `"Bb"`, `"F##3"`,
- * `"Ebb2"`. Both `#` and `x` (double-sharp) are accepted for sharps; `b` for
- * flats. Mixing sharps and flats (e.g. `"C#b"`) is rejected.
- *
- * @param text The note text.
- * @returns The parsed note.
- * @throws If the text is not a valid note.
- * @example
- * ```ts
- * import { parseNote, noteToMidi } from '@libraz/libcantus';
- * const n = parseNote('C#4');
- * noteToMidi(n); // 61
- * ```
- * @category Pitch & Intervals
- */
-declare function parseNote(text: string): Note;
-/**
- * Render a {@link Note} as scientific pitch notation.
- *
- * @param note The note to format.
- * @returns The note text, including the octave when present.
- * @example
- * ```ts
- * import { formatNote, parseNote } from '@libraz/libcantus';
- * formatNote(parseNote('C#4')); // 'C#4'
- * ```
- * @category Pitch & Intervals
- */
-declare function formatNote(note: Note): string;
-/**
- * Pitch class (0..11) of a note, ignoring octave.
- *
- * @param note The note.
- * @returns The pitch class.
- * @example
- * ```ts
- * import { noteToPitchClass, parseNote } from '@libraz/libcantus';
- * noteToPitchClass(parseNote('Db')); // 1
- * ```
- * @category Pitch & Intervals
- */
-declare function noteToPitchClass(note: Note): number;
-/**
- * MIDI number of a note (middle C = C4 = 60).
- *
- * @param note The note; must carry an octave.
- * @returns The MIDI number.
- * @throws If the note has no octave.
- * @example
- * ```ts
- * import { noteToMidi, parseNote } from '@libraz/libcantus';
- * noteToMidi(parseNote('A4')); // 69
- * ```
- * @category Pitch & Intervals
- */
-declare function noteToMidi(note: Note): number;
-/**
- * Name a MIDI number as a {@link Note}, choosing sharp or flat spelling.
- *
- * The input is rounded to the nearest integer but is not clamped to the MIDI
- * range 0..127: out-of-range values extrapolate linearly (e.g. `-1` -> `B-2`,
- * `128` -> `G#9`) and remain an exact inverse of {@link noteToMidi}.
- *
- * @param midi The MIDI number.
- * @param spelling Whether to prefer sharps or flats for black keys.
- * @returns The spelled note, with octave.
- * @example
- * ```ts
- * import { midiToNote, formatNote } from '@libraz/libcantus';
- * formatNote(midiToNote(61)); // 'C#4'
- * formatNote(midiToNote(61, 'flat')); // 'Db4'
- * ```
- * @category Pitch & Intervals
- */
-declare function midiToNote(midi: number, spelling?: 'sharp' | 'flat'): Note;
-/**
- * Transpose a note by a signed number of semitones, keeping its spelling.
- *
- * The letter moves by the diatonic distance of the conventional interval for
- * that many semitones and the accidental is recomputed for the new letter, so
- * enharmonic identity survives: `Ab4` up a major second is `Bb4`, not `A#4`, and
- * the operation is an exact inverse of itself. An octave-less note stays
- * octave-less.
- *
- * A bare semitone count cannot distinguish an augmented fourth from a diminished
- * fifth; pass `spelling` to override the letter distance when the enharmonic
- * choice matters.
- *
- * @param note The note to transpose.
- * @param semitones The signed semitone offset.
- * @param opts `spelling` forces the result onto the sharp or flat side instead
- *   of following the source note's letter.
- * @returns The transposed note.
- * @example
- * ```ts
- * import { transposeNote, formatNote, parseNote } from '@libraz/libcantus';
- * formatNote(transposeNote(parseNote('Ab4'), 2)); // 'Bb4'
- * formatNote(transposeNote(parseNote('Ab4'), 2, { spelling: 'sharp' })); // 'A#4'
- * ```
- * @category Pitch & Intervals
- */
-declare function transposeNote(note: Note, semitones: number, opts?: {
-    spelling?: 'sharp' | 'flat';
-}): Note;
-/**
- * The semitone span of the interval named by a diatonic number and a quality.
- *
- * The inverse of the quality derivation in {@link spelledInterval}: it turns a
- * name back into a distance, which is what transposing by a named interval or
- * parsing one from text needs.
- *
- * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
- * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
- * @returns The unsigned semitone span.
- * @throws If the quality cannot apply to the number, such as a major fifth.
- * @example
- * ```ts
- * import { intervalSemitones } from '@libraz/libcantus';
- * intervalSemitones(5, 'P'); // 7
- * ```
- * @category Pitch & Intervals
- */
-declare function intervalSemitones(numberValue: number, quality: IntervalQualityLabel): number;
-/**
- * Parse an interval name such as `'P5'`, `'m3'`, or `'AA4'`.
- *
- * @param name The interval name: a quality label followed by a diatonic number.
- * @returns The spelled interval, with an ascending (positive) span.
- * @throws If the name is not a quality label followed by a number, or the two
- *   cannot describe the same interval.
- * @example
- * ```ts
- * import { parseInterval } from '@libraz/libcantus';
- * parseInterval('m3'); // { number: 3, quality: 'm', semitones: 3 }
- * ```
- * @category Pitch & Intervals
- */
-declare function parseInterval(name: string): SpelledInterval;
-/**
- * Transpose a note by a spelled interval, keeping the spelling the interval
- * names.
- *
- * Unlike {@link transposeNote}, which picks a letter from the semitone count,
- * the diatonic number decides the letter here: transposing C by an augmented
- * second gives D#, not Eb.
- *
- * @param note The note to transpose.
- * @param interval The interval to apply; a negative span transposes downward.
- * @returns The transposed note, octave-less if the source was.
- * @example
- * ```ts
- * import { formatNote, parseInterval, parseNote, transposeByInterval } from '@libraz/libcantus';
- * formatNote(transposeByInterval(parseNote('C4'), parseInterval('A2'))); // 'D#4'
- * ```
- * @category Pitch & Intervals
- */
-declare function transposeByInterval(note: Note, interval: SpelledInterval): Note;
-/**
- * The spelled interval from one note to another.
- *
- * When both notes carry octaves, the interval reflects their full signed
- * distance (so `C4 -> C5` is a perfect octave). When either lacks an octave the
- * interval is measured within a single ascending octave from `a` to `b`.
- *
- * @param a The lower/first note.
- * @param b The upper/second note.
- * @returns The diatonic number, quality, and semitone span.
- * @example
- * ```ts
- * import { spelledInterval, parseNote } from '@libraz/libcantus';
- * spelledInterval(parseNote('C4'), parseNote('G4'));
- * // { number: 5, quality: 'P', semitones: 7 }
- * ```
- * @category Pitch & Intervals
- */
-declare function spelledInterval(a: Note, b: Note): SpelledInterval;
-
-export { type IntervalQualityLabel as I, type Note as N, type SpelledInterval as S, noteToMidi as a, noteToPitchClass as b, parseNote as c, diatonicLetterOf as d, pitchClassOf as e, formatNote as f, transposeNote as g, intervalSemitones as i, midiToNote as m, naturalPitchClassOf as n, parseInterval as p, spelledInterval as s, transposeByInterval as t };