@libraz/libcantus 0.9.4 → 1.0.0

package/dist/index-BkGmlyI3.d.cts

@@ -0,0 +1,470 @@
+import { P as ParseResult } from './index-B9MNZboQ.cjs';
+
+/**
+ * Meter arithmetic shared by the meter module and the validation guards.
+ *
+ * These helpers never validate: they are the single definition of how a time
+ * signature is read, so the guard that rejects a malformed signature and the
+ * functions that use a validated one cannot drift apart. Everything here is
+ * integer arithmetic on the numerator, so a bar's pulse count is exact rather
+ * than the result of dividing two floats.
+ */
+
+/**
+ * A meter in the plain data the library reads it as: one signature, or the map
+ * of a piece that changes meter.
+ *
+ * What {@link MeterLike} resolves to, and the type every function below the
+ * entry points works in — the text form is read once, at the boundary.
+ *
+ * @category Rhythm & Meter
+ */
+type MeterData = TimeSignature | MeterMap;
+
+/**
+ * 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).
+ * Beat 0 is the first downbeat, so a pickup sounds at negative beats, and a
+ * piece that changes meter is described by a {@link MeterMap} rather than by
+ * one signature.
+ */
+
+/**
+ * A time signature as a numerator over a note-value denominator.
+ *
+ * @category Rhythm & Meter
+ */
+type TimeSignature = {
+    numerator: number;
+    denominator: number;
+    /**
+     * Optional grouping of the bar into felt beats, as positive integers. The
+     * entries are group lengths, written either in the meter's main pulses —
+     * `[2, 2, 3]` for a 2+2+3 reading of 7/8, `[3, 2]` for 5/8 — or, for a
+     * compound numerator, in denominator units. They must sum to
+     * {@link pulsesPerBar} in the first spelling and to the numerator in the
+     * second; a pulse is one unit outside compound meters, where the two
+     * spellings coincide.
+     *
+     * A compound numerator accepts both readings, and the shape of the grouping
+     * says which is meant. Groups of nothing but threes spell the compound
+     * division itself, so 9/8 as `[3, 3, 3]` (equivalently `[1, 1, 1]`) is the
+     * ordinary three dotted-quarter pulses; any other grouping summing to the
+     * numerator reads additively, so 9/8 as `[2, 2, 2, 3]` is nine quaver pulses
+     * grouped aksak-fashion. {@link pulsesPerBar}, {@link pulseBeats} and
+     * {@link isCompound} follow whichever reading the grouping selects.
+     *
+     * The head pulse of each group other than the downbeat is a secondary strong
+     * pulse to {@link metricWeight}/{@link isStrongBeat}. A grouping whose groups
+     * are all the same length states no accent the meter does not already have,
+     * so it weighs exactly as an ungrouped bar does.
+     */
+    grouping?: number[];
+};
+/**
+ * One time signature and the beat at which it takes effect.
+ *
+ * @category Rhythm & Meter
+ */
+type MeterChange = {
+    /** Absolute quarter-note beat the signature takes effect at. */
+    startBeat: number;
+    /** The signature in force from that beat until the next change. */
+    ts: TimeSignature;
+};
+/**
+ * A piece's meter over time: the signatures in force, in beat order.
+ *
+ * A meter change starts a new bar, so a span that does not divide evenly into
+ * its own bars ends with a short bar rather than spilling across the change.
+ * The first entry also governs everything before it, which is what reads a
+ * pickup written at negative beats in the signature the piece opens in.
+ *
+ * @category Rhythm & Meter
+ */
+type MeterMap = MeterChange[];
+
+/**
+ * Anything that names a meter: a signature text such as `'6/8'`, a plain
+ * {@link TimeSignature}, a full {@link MeterMap}, or a value that serializes to
+ * one of those such as the `Meter` class.
+ *
+ * Every meter-aware function takes this, so a piece in one meter reads as
+ * `'4/4'` and a piece that changes meter reads as the map, without the caller
+ * choosing a different function for each. Only a signature has a text form — a
+ * meter map is a run of changes and is given as the data it is.
+ *
+ * @category Rhythm & Meter
+ */
+type MeterLike = string | TimeSignature | MeterMap | {
+    /** The meter data this value stands for. */
+    toJSON(): TimeSignature | MeterMap;
+};
+/**
+ * Resolve any meter-shaped value to the plain meter data the library reads.
+ *
+ * The counterpart of {@link toNoteData} for meters: an entry point takes
+ * whatever form the caller has — the signature a meter field holds, the data
+ * the meter module returns, the map of a piece that changes meter, or a `Meter`
+ * instance — and gets one of two shapes back. An instance is accepted through
+ * its `toJSON` method rather than by its type, so the core layer can read a
+ * class it cannot import.
+ *
+ * Text is read by {@link parseTimeSignature} and nothing else, so every entry
+ * point that takes a meter accepts exactly the signatures that parser accepts,
+ * the additive `'2+2+3/8'` included and nothing besides. A meter map has no text
+ * form — it is a run of changes, each with the beat it starts at — so text
+ * always names a single signature.
+ *
+ * @param value A signature text, a plain time signature, a meter map, or a
+ *   value whose `toJSON` returns one of those.
+ * @param name What the meter is called in an error message, so a caller that
+ *   holds several of them hears which one was malformed.
+ * @returns The validated signature, or the validated map.
+ * @throws If the value names no meter, or the meter it names is malformed.
+ */
+declare function toMeterData(value: MeterLike, name?: string): MeterData;
+/**
+ * A position expressed as a bar index and a quarter-note offset within the bar.
+ *
+ * @category Rhythm & Meter
+ */
+type BarPosition = {
+    /**
+     * 0-based bar index, counting the first full bar as 0.
+     * {@link formatBarPosition} renders it 1-based. A pickup sounds before that
+     * bar, so its notes report bar -1.
+     */
+    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"`, or the additive `"2+2+3/8"`.
+ *
+ * @param text The signature text.
+ * @returns The parsed time signature.
+ * @throws If the text is not `n/d` with positive integers, or names a signature
+ *   the library rejects. Use {@link tryParseTimeSignature} where failure is
+ *   ordinary, such as a meter field read on every keystroke.
+ * @example
+ * ```ts
+ * import { parseTimeSignature } from '@libraz/libcantus';
+ * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function parseTimeSignature(text: string): TimeSignature;
+/**
+ * Parse a time signature, reporting failure instead of throwing it.
+ *
+ * The same reading as {@link parseTimeSignature} — that function is this one
+ * with its error thrown — for the callers where text that does not parse yet is
+ * the normal state of the input rather than a fault.
+ *
+ * @param text The signature text.
+ * @returns The signature, or the error explaining why the text is not one.
+ * @example
+ * ```ts
+ * import { tryParseTimeSignature } from '@libraz/libcantus';
+ * const result = tryParseTimeSignature('7/8');
+ * result.ok ? result.value.numerator : result.error.message;
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function tryParseTimeSignature(text: string): ParseResult<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 additive form is what {@link parseTimeSignature} reads back, and it adds
+ * its terms to get the numerator — so only a grouping written in denominator
+ * units can be rendered that way. A grouping counted in main pulses (9/8 as
+ * `[1, 1, 1]`, 12/8 as `[2, 2]`) would come back as a different bar, so it
+ * falls back to the plain form, which those groupings cost nothing: they select
+ * the same reading the bare signature does.
+ *
+ * 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;
+/**
+ * The time signature in force at a beat.
+ *
+ * @param beatInQuarters Absolute position in quarter-note beats.
+ * @param meter A single signature, or the piece's meter map.
+ * @returns The signature governing that beat.
+ * @example
+ * ```ts
+ * import { meterAt, parseTimeSignature } from '@libraz/libcantus';
+ * const meters = [
+ *   { startBeat: 0, ts: parseTimeSignature('4/4') },
+ *   { startBeat: 8, ts: parseTimeSignature('3/4') },
+ * ];
+ * meterAt(9, meters); // { numerator: 3, denominator: 4 }
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function meterAt(beatInQuarters: number, meter: MeterLike): TimeSignature;
+/**
+ * Absolute beat at which the bar containing `beatInQuarters` begins.
+ *
+ * @param beatInQuarters Absolute position in quarter-note beats.
+ * @param meter A single signature, or the piece's meter map.
+ * @returns The bar's first beat, negative inside a pickup.
+ * @category Rhythm & Meter
+ */
+declare function barStartBeat(beatInQuarters: number, meter: MeterLike): number;
+/**
+ * Bar index of a beat: 0 for the first full bar, negative inside a pickup.
+ *
+ * Bars accumulate across meter changes, so the bar after a 4/4-to-3/4 change is
+ * the next bar and not the first bar of a new count.
+ *
+ * @param beatInQuarters Absolute position in quarter-note beats.
+ * @param meter A single signature, or the piece's meter map.
+ * @returns The 0-based bar index.
+ * @example
+ * ```ts
+ * import { barIndexAt, parseTimeSignature } from '@libraz/libcantus';
+ * const meters = [
+ *   { startBeat: 0, ts: parseTimeSignature('4/4') },
+ *   { startBeat: 8, ts: parseTimeSignature('3/4') },
+ * ];
+ * barIndexAt(11, meters); // 3
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function barIndexAt(beatInQuarters: number, meter: MeterLike): number;
+/**
+ * Length in quarter-note beats of the bar containing a beat.
+ *
+ * The meter-map counterpart of {@link beatsPerBar}, which answers for one
+ * signature and so cannot be asked about a piece that changes meter.
+ *
+ * @param beatInQuarters Absolute position in quarter-note beats.
+ * @param meter A single signature, or the piece's meter map.
+ * @returns The bar length in quarter notes.
+ * @category Rhythm & Meter
+ */
+declare function beatsPerBarAt(beatInQuarters: number, meter: MeterLike): number;
+/**
+ * Read the meter out of a pair of options that accept either form.
+ *
+ * Entry points take `meters` for a piece that changes meter and keep `ts` as
+ * sugar for a piece that does not, so this is the one place that resolves the
+ * pair — including the rule that naming both is an input error rather than one
+ * of them silently winning.
+ *
+ * @param opts The options carrying `ts`, `meters`, or neither.
+ * @param name What the options belong to, for the error message.
+ * @returns The meter map to analyse against; 4/4 throughout when neither is given.
+ * @throws If both `ts` and `meters` are given, or the map is malformed.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, resolveMeters } from '@libraz/libcantus';
+ * resolveMeters({ ts: parseTimeSignature('3/4') });
+ * // [{ startBeat: 0, ts: { numerator: 3, denominator: 4 } }]
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function resolveMeters(opts: {
+    ts?: TimeSignature;
+    meters?: MeterMap;
+}, name?: string): MeterMap;
+/**
+ * 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 meter A single signature, or the piece's meter map.
+ * @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, meter: MeterLike): 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 meter A single signature, or the piece's meter map.
+ * @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, meter: MeterLike): number;
+/**
+ * Render an absolute position as the `bar.beat` a DAW or a score shows:
+ * 1-based bar, 1-based felt beat.
+ *
+ * The felt beats counted are the ones the bar actually has. A meter change
+ * starts a new bar, so the bar it interrupts is short, and a position that
+ * rounds past the end of a short bar reads as the downbeat of the next one
+ * rather than as a beat the bar never reached.
+ *
+ * @param beatInQuarters Absolute position in quarter-note beats.
+ * @param meter A single signature, or the piece's meter map.
+ * @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, meter: MeterLike, decimals?: number): string;
+/**
+ * Convert a bar index and in-bar offset back to an absolute quarter-note
+ * position.
+ *
+ * @param pos The bar position.
+ * @param meter A single signature, or the piece's meter map.
+ * @returns The absolute position in quarter-note beats.
+ * @category Rhythm & Meter
+ */
+declare function barPositionToBeat(pos: BarPosition, meter: MeterLike): 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). A grouping of equal-length groups (9/8 as `[1, 1, 1]`, 4/4 as
+ * `[1, 1, 1, 1]`) states the division the meter already has, so it weighs as
+ * an ungrouped bar rather than accenting every group head.
+ *
+ * Given a meter map, the weight follows the signature in force at that beat, so
+ * beat 5 of a piece is a mid-bar accent in 4/4 and a plain main pulse in 3/4.
+ * The downbeat is beat 0 however much pickup precedes it, so a note in the
+ * pickup weighs as the upbeat it is rather than as a downbeat.
+ *
+ * @param beatInQuarters Absolute quarter-note position, or an in-bar offset
+ *   when the meter is a single signature.
+ * @param meter A single signature, or the piece's meter map.
+ * @returns The metric weight (0–3).
+ * @throws If the meter 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, meter: MeterLike): number;
+/**
+ * Whether a position is metrically accented (weight 2 or more — a downbeat or a
+ * secondary strong pulse).
+ *
+ * @param beatInQuarters Absolute quarter-note position, or an in-bar offset
+ *   when the meter is a single signature.
+ * @param meter A single signature, or the piece's meter map.
+ * @returns True on strong beats.
+ * @category Rhythm & Meter
+ */
+declare function isStrongBeat(beatInQuarters: number, meter: MeterLike): 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 MeterChange as M, type TimeSignature as T, type MeterData as a, type MeterLike as b, type MeterMap as c, barIndexAt as d, barPositionToBeat as e, barPositionToPulse as f, barStartBeat as g, beatToBarPosition as h, beatsPerBar as i, beatsPerBarAt as j, formatBarPosition as k, formatTimeSignature as l, isCompound as m, isStrongBeat as n, meterAt as o, metricWeight as p, parseTimeSignature as q, pulseBeats as r, pulsesPerBar as s, resolveMeters as t, toMeterData as u, tryParseTimeSignature as v, tuplet as w };