@libraz/libcantus 1.0.1 → 1.2.0

package/dist/{index-Chbst3Jx.d.ts → index-CJBBiAmU.d.ts}

@@ -1,6 +1,6 @@
-import { c as ChordLike, K as KeyLike, j as ChordToneRole, b as Chord, k as KeyRelation, e as ChordSegment, V as VoiceSnapshot, g as ChordSpan } from './index-szBv3496.js';
-import { T as TimeSignature, c as MeterMap } from './index-Cj49F892.js';
-import { d as KeyScale, g as NoteEvent } from './index-B9MNZboQ.js';
+import { c as ChordLike, K as KeyLike, i as ChordToneRole, r as SpelledKeyLike, b as Chord, n as ResolvedKey, j as KeyRelation, e as ChordSegment, V as VoiceSnapshot, g as ChordSpan } from './coerce-DP0vYu-x.js';
+import { b as MeterLike } from './index-CL4b4gUQ.js';
+import { h as NoteEvent, e as KeyScale } from './index-Cy15oTvh.js';
 
 /**
  * The vocabulary the analyze layer explains itself in.
@@ -222,33 +222,41 @@ type DetectCadenceOptions = {
  * Classify the cadence formed by moving from one chord to the next.
  *
  * - authentic: V (dominant a fifth above the tonic) to I
- * - plagal: IV (a fourth above the tonic) to I
+ * - plagal: IV, the chord on the key's own fourth degree, to I
  * - modal: bVII to I, the cadence of rock and modal writing
  * - deceptive: V to the key's own submediant, plus the borrowed bVI of a major
  *   key
  * - phrygian: iv6 to V of a minor key, the half cadence whose bass falls a
  *   semitone from b6 to 5
- * - half: any other chord than the dominant itself to V
- *
- * Both are read as scale degrees rather than as semitone distances, so a mode
- * cadences onto the submediant and the dominant it actually has: the deceptive
- * arrival of dorian is a major sixth above the tonic and that of phrygian a
- * minor sixth. A half cadence normally rests on the major third that carries
- * the leading tone, but where the key's own dominant has no leading tone —
- * aeolian and dorian, the modal `v` of pop writing — the arrival's own third
- * suffices as long as the key contains it. That relaxation never applies to a
- * key whose dominant does carry the leading tone, so a borrowed minor `v` in a
- * major key is no half cadence.
+ * - half: any other chord than the dominant itself to V, the cadential six-four
+ *   standing on the dominant's own bass included
+ *
+ * These are read as scale degrees rather than as semitone distances, so a mode
+ * cadences from and onto the degrees it actually has: the deceptive arrival of
+ * dorian is a major sixth above the tonic and that of phrygian a minor sixth,
+ * and the subdominant a plagal cadence falls from is the tritone above the
+ * tonic in lydian. The two borrowed types are the exception, and are stated as
+ * the fixed offsets they name: `modal` is the flattened seventh whatever the
+ * key writes on that degree, and the Phrygian bass falls from the lowered
+ * submediant. A half cadence normally rests on the major third that carries
+ * the leading tone, but where the key's own dominant has no leading tone — the
+ * modal `v` of dorian, mixolydian and the pop writing built on them — the
+ * arrival's own third suffices as long as the key contains it. That relaxation
+ * belongs to the modes alone: a borrowed minor `v` in a major key is no half
+ * cadence, and neither is the `v` of a minor key, which cadences through the
+ * raised seventh it writes as an accidental rather than in its scale.
  *
  * A static V-to-V repeat with no root motion is not a cadence and yields a null
- * type, and so is the tonic six-four resolving onto the dominant it already
- * stands on: that pair is one harmony moving inside itself. Passing that
- * six-four as `approach` when the dominant is the `from` chord is what lets the
- * cadence be reported as the single event it is — the type and the beat are
- * still the dominant's resolution, while the `rationale` says the cadence began
- * at the six-four. A six-four the bass leaves instead (`IV-I64-IV`, or a
- * neighbouring one over the tonic) is an ordinary inverted tonic and is read as
- * one.
+ * type. The tonic six-four resolving onto the dominant it stands on is a half
+ * cadence, and the most ordinary one there is: `I - I64 - V` closes the
+ * antecedent of a period, and the six-four is a double appoggiatura over the
+ * dominant's own bass rather than a chord that keeps the motion going. Where
+ * that dominant goes on to resolve, the pair and the resolution are one event —
+ * passing the six-four as `approach` when the dominant is the `from` chord is
+ * what lets it be reported as one, with the type and the beat still the
+ * dominant's resolution while the `rationale` says the cadence began at the
+ * six-four. A six-four the bass leaves instead (`IV-I64-IV`, or a neighbouring
+ * one over the tonic) is an ordinary inverted tonic and is read as one.
  *
  * An authentic cadence is graded perfect or imperfect. Perfect takes the
  * dominant to the tonic with both chords in root position and the tonic in the
@@ -336,7 +344,7 @@ declare function detectCadence(from: ChordLike, to: ChordLike, key: KeyLike, opt
  * ```
  * @category Functional Harmony
  */
-declare function romanToChord(text: string, key: KeyLike): Chord;
+declare function romanToChord(text: string, key: SpelledKeyLike): Chord;
 /**
  * Options for {@link chordToRoman}.
  *
@@ -350,10 +358,17 @@ type ChordToRomanOptions = {
      * Off by default: naming the root is always a correct spelling, whereas
      * whether a chromatic dominant is genuinely applied is a reading only the
      * caller can make. Turning it on names the chords {@link secondaryDominant}
-     * builds as the applied numerals they are, except where the target degree
-     * carries no perfect fifth: nothing tonicizes a diminished triad, so a chord
-     * over the seventh degree of a major key stays `#IV7` rather than becoming a
-     * numeral no harmony text writes.
+     * builds as the applied numerals they are, except in three cases, where the
+     * numeral names the root against the home key as it does with this off:
+     *
+     * - The target degree carries no perfect fifth: nothing tonicizes a
+     *   diminished triad, so a chord over the seventh degree of a major key stays
+     *   `#IV7` rather than becoming a numeral no harmony text writes.
+     * - The target is the tonic, which its own dominant points at: `V7` is the
+     *   key's dominant and `V/I` is a numeral no harmony text writes either.
+     * - The chord is diatonic to the key, which keeps the function of its degree
+     *   rather than tonicizing another. `G7` is `VII7` in A minor and `I7` in C
+     *   mixolydian, not `V7/III` and `V7/IV`.
      */
     applied?: boolean;
     /**
@@ -392,6 +407,11 @@ type ChordToRomanOptions = {
  * A chord sounding one of the augmented sixths over an explicit bass on the
  * lowered submediant renders as `It6`, `Fr6` or `Ger6`, since no numeral names
  * those chords; see {@link augmentedSixthKind} for exactly when that applies.
+ * That reading is made against the key as written, because what separates an
+ * augmented sixth from the seventh chord it sounds like is its letters: the
+ * German sixth of Ab minor is named from the Fb Ab Cb D it is written with, not
+ * from the letters those pitch classes take once the key has been respelled as
+ * a G# minor.
  *
  * @param chord The chord to name, as a chord symbol, chord data, or a `Chord`.
  * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
@@ -502,11 +522,14 @@ declare function isMinorKey(key: KeyLike): boolean;
  * an ambiguity the root offset cannot:
  *
  * - A chord that *sounds* like a dominant — a major third with a minor seventh,
- *   or a diminished-family chord — and is not diatonic to the key has dominant
- *   function when its root resolves down a fifth or by a semitone onto a
- *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
- *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
- *   than inheriting the function of the degree they happen to sit on.
+ *   or a diminished-family chord — and is neither diatonic to the key nor
+ *   borrowed from its parallel mode has dominant function when its root
+ *   resolves onto a degree that can be made a local tonic. This is what makes an
+ *   applied dominant (`A7` in C, which tonicizes ii) and its tritone substitute
+ *   (`Db7`) read as dominant rather than inheriting the function of the degree
+ *   they happen to sit on. A bare major triad carries no tritone, so it only
+ *   tonicizes by falling a fifth onto a degree other than the tonic: the Picardy
+ *   third of a minor key and its borrowed major IV sound their own degrees.
  * - The Neapolitan is subdominant.
  * - An augmented sixth is subdominant. All three are altered predominants that
  *   resolve outward onto the dominant, so they take subdominant function even
@@ -646,8 +669,8 @@ declare function secondaryDominant(targetDegree: number, key: KeyLike): Chord;
  * @example
  * ```ts
  * import { makeChord, secondaryDominantOf } from '@libraz/libcantus';
- * secondaryDominantOf(makeChord(8, 'maj'));
- * // { rootPc: 3, quality: 'dom7' } — Eb7 tonicizes the borrowed bVI of C major
+ * secondaryDominantOf(makeChord(8, 'maj')).rootPc; // 3 — Eb7 tonicizes the
+ * // borrowed bVI of C major
  * ```
  * @category Functional Harmony
  */
@@ -727,8 +750,20 @@ type KeyRegion = {
     startBeat: number;
     /** End of the region, exclusive. */
     endBeat: number;
-    /** The key in force across the region. */
-    key: KeyScale;
+    /**
+     * The key in force across the region, owned by it: every entry point hands
+     * back a key of the region's own, so writing to one changes neither the other
+     * regions of the same run nor what a later call reports.
+     *
+     * Whole, whichever way the region was built. A caller who named the key hands
+     * its spelling and scale form down, and a key the analysis found is spelled
+     * and formed the way {@link resolveKey} reads a bare scale — the reading every
+     * other layer would have made of it. There is no third state to guess at: a
+     * key/scale alone says nothing about how it is written, so a region carrying
+     * one would report whichever spelling those pitch classes read best from, and
+     * an Ab minor handed in would come back out a G# minor.
+     */
+    key: ResolvedKey;
     /**
      * How well the region's music fits the key, in [0, 1]: the correlation
      * between the span's pitch-class distribution and the key's profile, with
@@ -770,7 +805,7 @@ type KeyTimelineOptions = {
      *
      * @defaultValue `4/4`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * The meter as it changes over the span. Bar lines, downbeats and the metric
      * accents the search discounts a modulation by all follow the signature in
@@ -779,7 +814,7 @@ type KeyTimelineOptions = {
      *
      * @defaultValue 4/4 throughout
      */
-    meters?: MeterMap;
+    meters?: MeterLike;
     /**
      * Expected length of one key area in beats; defaults to four bars of the
      * opening meter.
@@ -881,6 +916,12 @@ declare function keyTimelineFromNotes(notes: readonly NoteEvent[], opts?: KeyTim
  * confidence, as it does in the note path, but takes no part in choosing which
  * keys are reported: that is settled by how the chords read.
  *
+ * A region's evidence is the run of segments it was grouped from, which is the
+ * same reading the search itself makes of them. Where the segments given
+ * overlap each other — a chart is a sequence, so a chord timeline's are not —
+ * a chord held past the segment after it argues for its own segment's key
+ * rather than for both.
+ *
  * @param chords The chord segments to analyze, in time order; pass a chord
  *   timeline's `segments`.
  * @param opts Analysis options; see {@link KeyTimelineOptions}.
@@ -916,7 +957,7 @@ declare function detectModulations(chords: readonly ChordSegment[], opts?: KeyTi
  * ```
  * @category Arrangement & Analysis
  */
-declare function prevailingKeyOf(regions: readonly KeyRegion[]): KeyScale | null;
+declare function prevailingKeyOf(regions: readonly KeyRegion[]): ResolvedKey | null;
 
 /**
  * A suspension figure, named by the interval above the bass and the interval it
@@ -1033,7 +1074,7 @@ type IdentifiedVoiceNote = VoiceNote & {
  * ```
  * @category Arrangement & Analysis
  */
-type KeyContext = KeyScale | ((beat: number) => KeyScale);
+type KeyContext = KeyLike | ((beat: number) => KeyScale);
 /**
  * Give plain note events the ids {@link analyzeVoice} reports back.
  *
@@ -1055,8 +1096,10 @@ declare function toVoiceNotes(events: readonly NoteEvent[]): IdentifiedVoiceNote
  * resolving by step the other way), and escape tones, then fall back to
  * tension, avoid, or an unresolved-dissonance label. The figures are named as
  * {@link classifyMelodyTones} names them, so a caller reading a melody through
- * both layers gets one vocabulary; that classifier weighs the metre as well,
- * which this one is not given, so it is the stricter of the two. Leading-tone resolutions are noted
+ * both layers gets one vocabulary. The two answer different questions and
+ * neither refines the other: that classifier weighs the metre, which this one is
+ * not given, so it can call ornamental a note this one reads as a chord tone,
+ * and the reverse. Leading-tone resolutions are noted
  * additionally, judged against the key in force at the beat the resolution
  * lands on, so a modulation is heard from its new tonic.
  *
@@ -1103,6 +1146,32 @@ type ChordTimeline = {
     at: (beat: number) => Chord | null;
     segments: ChordSegment[];
 };
+/**
+ * Reject a value that is not a chord timeline.
+ *
+ * A timeline is the one argument a host is most likely to hold from somewhere
+ * else — an in-memory project value, a previous run restored to a timeline, or
+ * another library's output — and
+ * it is read field by field deep inside an analysis. Checking it once at the
+ * entrance names the argument that is wrong instead of reporting the library's
+ * own `TypeError` from wherever the first `segments` lookup happened to be.
+ *
+ * The segments are checked too: every reader of a timeline compares beats, and
+ * a segment whose bounds are missing compares as neither before nor after, so
+ * it disappears from the analysis rather than being reported.
+ *
+ * @param timeline The timeline as the caller passed it.
+ * @param name What the argument is called in an error message.
+ * @returns The same timeline.
+ * @throws If the value is not a timeline of chord segments.
+ * @example
+ * ```ts
+ * import { assertChordTimeline, chordTimelineFromChords } from '@libraz/libcantus';
+ * assertChordTimeline(chordTimelineFromChords([], 4)); // the timeline, unchanged
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function assertChordTimeline(timeline: ChordTimeline, name?: string): ChordTimeline;
 /**
  * Build a chord timeline from placed chords.
  *
@@ -1139,15 +1208,19 @@ type ChordTimelineOptions = {
      * Key context held across the whole span. Omit it to have the key searched
      * for over time with {@link keyTimelineFromNotes}, which is what lets a piece
      * that modulates be analysed against the key actually in force.
+     *
+     * Taken in whatever form the caller holds a key, and kept whole: the region
+     * built from it carries the spelling and the scale form it was named with, so
+     * an Ab minor stated here is an Ab minor in the result.
      */
-    key?: KeyScale;
+    key?: KeyLike;
     /**
      * A single time signature held across the whole span, as sugar for a
      * one-element `meters`; defaults to 4/4. Giving both is an input error.
      *
      * @defaultValue `4/4`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * The meter as it changes over the span. Bar lines, downbeats and metric
      * weight all follow the signature in force at the beat in question, so a
@@ -1155,7 +1228,7 @@ type ChordTimelineOptions = {
      *
      * @defaultValue 4/4 throughout
      */
-    meters?: MeterMap;
+    meters?: MeterLike;
     /**
      * Length of the pickup in beats, when the piece starts with one.
      *
@@ -1184,18 +1257,21 @@ type ChordTimelineOptions = {
      */
     harmonicRhythm?: number;
     /**
-     * Shortest chord the `'dynamic'` search may report, in beats; defaults to one
-     * beat. Lower it to catch changes on off-beats, at the cost of proportionally
-     * more work. Values above `harmonicRhythm` are clamped to it, and the option
-     * is ignored under `'grid'` segmentation.
+     * Resolution the `'dynamic'` search looks for changes at, in beats; defaults
+     * to one main pulse of the meter — a quarter in 4/4, a dotted quarter in 6/8.
+     * Lower it to catch changes on off-beats, at the cost of proportionally more
+     * work. Values above `harmonicRhythm` are clamped to it, and the option is
+     * ignored under `'grid'` segmentation.
      *
      * The search reads it as a resolution rather than as an exact slot length: it
-     * rounds down to a whole division of `harmonicRhythm`, so `0.6` against a
-     * four-beat chord is read in sevenths of it. That keeps the beats one
-     * expected chord gives way to the next on the grid whatever resolution is
-     * asked for, and with them every change a coarser setting found.
+     * rounds down to a whole division of the meter's pulse, so `0.6` in 4/4 is
+     * read in half-beats. That keeps every pulse of the meter, and the bar lines
+     * with them, on the grid whatever resolution is asked for, and with them every
+     * change a coarser setting found. A resolution coarser than one pulse is
+     * therefore read as one pulse rather than stepping over the beats a change is
+     * heard on.
      *
-     * @defaultValue `1`
+     * @defaultValue one main pulse of the meter
      */
     minChordBeats?: number;
     /**
@@ -1237,7 +1313,7 @@ type ChordTimelineResult = {
      * The key held longest across {@link ChordTimelineResult.keys} — the one to
      * print on a key signature or hand to a generator that takes a single key.
      */
-    prevailingKey: KeyScale;
+    prevailingKey: ResolvedKey;
     /** One confidence value in [0, 1] per segment, in segment order. */
     segmentConfidence: number[];
 };
@@ -1245,7 +1321,8 @@ type ChordTimelineResult = {
  * Infer a chord timeline from raw multi-track notes.
  *
  * Chord boundaries are searched for rather than assumed: the span is examined
- * in `minChordBeats` slots, and the change points that best explain the notes
+ * in slots of one main pulse, subdivided as finely as `minChordBeats` asks for,
+ * and the change points that best explain the notes
  * are chosen, trading each slot's harmonic fit against a cost per chord change
  * that a strong beat discounts. A bar holding two chords therefore yields two
  * segments and a bar holding one yields one, without the caller having to know
@@ -1340,4 +1417,4 @@ type CadenceHit = {
  */
 declare function detectCadences(timeline: ChordTimeline, key: KeyContext): CadenceHit[];
 
-export { type AnalyzeChordOptions as A, type BorrowedSource as B, type CadenceHit as C, type DetectCadenceOptions as D, type ExplainRomanOptions as E, isMinorKey as F, keyTimelineFromNotes as G, type HarmonicFunction as H, type IdentifiedVoiceNote as I, pivotChords as J, type KeyContext as K, prevailingKeyOf as L, romanToChord as M, secondaryDominant as N, secondaryDominantOf as O, type PivotChord as P, toVoiceNotes as Q, type RejectedCandidate as R, type SuspensionFigure as S, type TheoryLabel as T, type VoiceNote as V, type AnalyzedNote as a, type CadenceResult as b, type ChordAnalysis as c, type ChordSegmentation as d, type ChordTimeline as e, type ChordTimelineOptions as f, type ChordTimelineResult as g, type ChordToRomanOptions as h, type KeyProfileName as i, type KeyProfilePair as j, type KeyRegion as k, type KeyTimelineOptions as l, type RomanExplanation as m, analyzeChord as n, analyzeVoice as o, borrowedSource as p, chordTimelineFromChords as q, chordTimelineFromNotes as r, chordToRoman as s, detectCadence as t, detectCadences as u, detectModulations as v, explainRoman as w, functionOf as x, isBorrowedChord as y, isDiatonic as z };
+export { type AnalyzeChordOptions as A, type BorrowedSource as B, type CadenceHit as C, type DetectCadenceOptions as D, type ExplainRomanOptions as E, isDiatonic as F, isMinorKey as G, type HarmonicFunction as H, type IdentifiedVoiceNote as I, keyTimelineFromNotes as J, type KeyContext as K, pivotChords as L, prevailingKeyOf as M, romanToChord as N, secondaryDominant as O, type PivotChord as P, secondaryDominantOf as Q, type RejectedCandidate as R, type SuspensionFigure as S, type TheoryLabel as T, toVoiceNotes as U, type VoiceNote as V, type AnalyzedNote as a, type CadenceResult as b, type ChordAnalysis as c, type ChordSegmentation as d, type ChordTimeline as e, type ChordTimelineOptions as f, type ChordTimelineResult as g, type ChordToRomanOptions as h, type KeyProfileName as i, type KeyProfilePair as j, type KeyRegion as k, type KeyTimelineOptions as l, type RomanExplanation as m, analyzeChord as n, analyzeVoice as o, assertChordTimeline as p, borrowedSource as q, chordTimelineFromChords as r, chordTimelineFromNotes as s, chordToRoman as t, detectCadence as u, detectCadences as v, detectModulations as w, explainRoman as x, functionOf as y, isBorrowedChord as z };

package/dist/{index-BkGmlyI3.d.cts → index-CL4b4gUQ.d.ts}

@@ -1,4 +1,4 @@
-import { P as ParseResult } from './index-B9MNZboQ.cjs';
+import { P as ParseResult } from './index-Cy15oTvh.js';
 
 /**
  * Meter arithmetic shared by the meter module and the validation guards.
@@ -83,6 +83,14 @@ type MeterChange = {
  * 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.
  *
+ * Beat 0 is the first downbeat here as everywhere else: the opening signature
+ * lays its bar lines from beat 0 whatever beat the first entry is written at, so
+ * a map opening at the pickup it covers numbers its bars exactly as the bare
+ * signature does. Every later entry starts a bar at the beat it takes effect.
+ *
+ * Pass the whole piece with its map rather than one call per meter span: a
+ * split call cannot see a voice move or a key region that crosses the change.
+ *
  * @category Rhythm & Meter
  */
 type MeterMap = MeterChange[];
@@ -123,7 +131,10 @@ type MeterLike = string | TimeSignature | MeterMap | {
  *   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.
+ * @returns The validated signature, or the validated map, freshly allocated
+ *   down to every grouping array — so a caller may keep and edit what it gets
+ *   back without editing the meter it passed in, and without any two calls
+ *   handing out the same object.
  * @throws If the value names no meter, or the meter it names is malformed.
  */
 declare function toMeterData(value: MeterLike, name?: string): MeterData;
@@ -186,17 +197,23 @@ declare function tryParseTimeSignature(text: string): ParseResult<TimeSignature>
  *
  * 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.
+ * units can be rendered that way. A grouping counted in main pulses whose groups
+ * are all the same length (9/8 as `[1, 1, 1]`, 12/8 as `[2, 2]`) states the
+ * division the bare signature already has, so it falls back to the plain form at
+ * no cost. One whose groups differ (12/8 as `[1, 1, 2]`) states an accent no
+ * signature text can carry, and asking for the additive form of it is refused
+ * rather than answered with a bar that weighs its pulses differently.
  *
  * 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 ts The time signature, in any form that names one; a meter map is
+ *   rendered as the signature it opens in.
  * @param opts Set `grouping: true` to render an additive grouping.
  * @returns The formatted signature.
+ * @throws If `grouping: true` is asked of a grouping that no signature text can
+ *   spell: one counted in main pulses, on a compound numerator, whose groups are
+ *   not all the same length.
  * @example
  * ```ts
  * import { formatTimeSignature } from '@libraz/libcantus';
@@ -206,7 +223,7 @@ declare function tryParseTimeSignature(text: string): ParseResult<TimeSignature>
  * ```
  * @category Rhythm & Meter
  */
-declare function formatTimeSignature(ts: TimeSignature, opts?: {
+declare function formatTimeSignature(ts: MeterLike, opts?: {
     grouping?: boolean;
 }): string;
 /**
@@ -217,19 +234,27 @@ declare function formatTimeSignature(ts: TimeSignature, opts?: {
  * is a signature whose {@link TimeSignature.grouping} selects the additive
  * reading (9/8 as 2+2+2+3).
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map is read
+ *   as the signature it opens in.
  * @returns True for compound meters.
  * @category Rhythm & Meter
  */
-declare function isCompound(ts: TimeSignature): boolean;
+declare function isCompound(ts: MeterLike): boolean;
 /**
  * Length of a bar in quarter-note beats.
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map has no
+ *   single bar length, so it is read as the signature it opens in. Ask
+ *   {@link beatsPerBarAt} for the bar a given beat falls in.
  * @returns The bar length in quarter notes.
+ * @example
+ * ```ts
+ * import { beatsPerBar } from '@libraz/libcantus';
+ * beatsPerBar('6/8'); // 3
+ * ```
  * @category Rhythm & Meter
  */
-declare function beatsPerBar(ts: TimeSignature): number;
+declare function beatsPerBar(ts: MeterLike): number;
 /**
  * The time signature in force at a beat.
  *
@@ -284,6 +309,12 @@ declare function barIndexAt(beatInQuarters: number, meter: MeterLike): number;
  * The meter-map counterpart of {@link beatsPerBar}, which answers for one
  * signature and so cannot be asked about a piece that changes meter.
  *
+ * The bar the beat is in, not the bar its signature nominally has: a change of
+ * meter starts a new bar, so a bar interrupted by one is shorter than its own
+ * signature says. Reading the signature's own length there would put the end of
+ * the bar past where the next one begins, and every span measured in bars from
+ * that point on would be counted against a bar length the music never had.
+ *
  * @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.
@@ -300,7 +331,9 @@ declare function beatsPerBarAt(beatInQuarters: number, meter: MeterLike): number
  *
  * @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.
+ * @returns The meter map to analyse against, freshly allocated down to every
+ *   signature and grouping array, so writing to it changes nothing another
+ *   caller reads; 4/4 throughout when neither `ts` nor `meters` is given.
  * @throws If both `ts` and `meters` are given, or the map is malformed.
  * @example
  * ```ts
@@ -311,8 +344,8 @@ declare function beatsPerBarAt(beatInQuarters: number, meter: MeterLike): number
  * @category Rhythm & Meter
  */
 declare function resolveMeters(opts: {
-    ts?: TimeSignature;
-    meters?: MeterMap;
+    ts?: MeterLike;
+    meters?: MeterLike;
 }, name?: string): MeterMap;
 /**
  * Number of main pulses (felt beats) per bar: the numerator for simple meters,
@@ -324,11 +357,12 @@ declare function resolveMeters(opts: {
  * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
  * group's head pulse.
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map is read
+ *   as the signature it opens in.
  * @returns The pulse count per bar.
  * @category Rhythm & Meter
  */
-declare function pulsesPerBar(ts: TimeSignature): number;
+declare function pulsesPerBar(ts: MeterLike): number;
 /**
  * Convert an absolute quarter-note position to a bar index and in-bar offset.
  *
@@ -351,16 +385,17 @@ declare function beatToBarPosition(beatInQuarters: number, meter: MeterLike): Ba
  * denominator unit in an additive metre. Position displays, click tracks, and
  * score export are all written against this length.
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map is read
+ *   as the signature it opens in.
  * @returns The pulse length in quarter-note beats.
  * @example
  * ```ts
- * import { parseTimeSignature, pulseBeats } from '@libraz/libcantus';
- * pulseBeats(parseTimeSignature('6/8')); // 1.5
+ * import { pulseBeats } from '@libraz/libcantus';
+ * pulseBeats('6/8'); // 1.5
  * ```
  * @category Rhythm & Meter
  */
-declare function pulseBeats(ts: TimeSignature): number;
+declare function pulseBeats(ts: MeterLike): number;
 /**
  * The felt-beat number of a bar position, 1-based.
  *
@@ -391,11 +426,16 @@ declare function barPositionToPulse(pos: BarPosition, meter: MeterLike): number;
  * @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.
+ * @returns The formatted position in one of two forms: `bar.beat` on a felt
+ *   beat, e.g. `'3.2'` for bar 3, felt beat 2; and `bar.beat+fraction` between
+ *   felt beats, e.g. `'3.2+0.5'` halfway from the second felt beat to the third.
+ *   A reader of these strings has to take both, since most onsets of an ordinary
+ *   piece fall between pulses.
  * @example
  * ```ts
  * import { formatBarPosition, parseTimeSignature } from '@libraz/libcantus';
  * formatBarPosition(7.5, parseTimeSignature('6/8')); // '3.2'
+ * formatBarPosition(8.25, parseTimeSignature('6/8')); // '3.2+0.5'
  * ```
  * @category Rhythm & Meter
  */
@@ -425,7 +465,7 @@ declare function barPositionToBeat(pos: BarPosition, meter: MeterLike): number;
  * 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.
+ * beat 2 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.
  *