@libraz/libcantus 0.9.0 → 0.9.2

package/src/{timeline → analyze/timeline}/index.ts

@@ -1,23 +1,30 @@
-import type { Chord } from '../chord/index.js';
-import { chordPitchClasses, makeChord } from '../chord/index.js';
+import type { TimeSignature } from '../../core/meter/index.js';
+import { beatsPerBar, metricWeight, parseTimeSignature } from '../../core/meter/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import type { Chord, ChordSpan } from '../../theory/chord/index.js';
+import { chordPitchClasses, makeChord } from '../../theory/chord/index.js';
+import { isScaleTone, majorKey } from '../../theory/scale/index.js';
 import type { ChordMatch } from '../detect/index.js';
 import { detectChord, detectChordBest, detectKey } from '../detect/index.js';
 import type { Cadence } from '../functional/index.js';
 import { detectCadence } from '../functional/index.js';
-import type { TimeSignature } from '../meter/index.js';
-import { beatsPerBar, metricWeight, parseTimeSignature } from '../meter/index.js';
-import type { GeneratedChord } from '../progression/index.js';
-import { isScaleTone, majorKey } from '../scale/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
 
-/** A chord occupying a half-open beat span. */
+/**
+ * A chord occupying a half-open beat span.
+ *
+ * @category Arrangement & Analysis
+ */
 export type ChordSegment = {
   startBeat: number;
   endBeat: number;
   chord: Chord;
 };
 
-/** A beat-indexed sequence of chord segments. */
+/**
+ * A beat-indexed sequence of chord segments.
+ *
+ * @category Arrangement & Analysis
+ */
 export type ChordTimeline = {
   /** The chord sounding at a beat, or null when no segment covers it. */
   at: (beat: number) => Chord | null;
@@ -35,11 +42,9 @@ export type ChordTimeline = {
  * @param chords Placed chords in time order.
  * @param totalBeats End of the timeline in beats.
  * @returns A queryable chord timeline.
+ * @category Arrangement & Analysis
  */
-export function chordTimelineFromChords(
-  chords: GeneratedChord[],
-  totalBeats: number,
-): ChordTimeline {
+export function chordTimelineFromChords(chords: ChordSpan[], totalBeats: number): ChordTimeline {
   const sorted = [...chords].sort((a, b) => a.startBeat - b.startBeat);
   const segments: ChordSegment[] = sorted
     .map((gc, i) => {
@@ -96,19 +101,39 @@ function pitchClass(value: number): number {
   return ((Math.trunc(value) % 12) + 12) % 12;
 }
 
-/** Options controlling {@link chordTimelineFromNotes}. */
+/**
+ * Options controlling {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
 export type ChordTimelineOptions = {
   /** Key context; inferred from the notes with {@link detectKey} when omitted. */
   key?: KeyScale;
-  /** Time signature used for metric accents; defaults to 4/4. */
+  /**
+   * Time signature used for metric accents; defaults to 4/4.
+   *
+   * @defaultValue `4/4`
+   */
   ts?: TimeSignature;
-  /** Window length in beats per chord slot; defaults to one bar of `ts`. */
+  /**
+   * Window length in beats per chord slot; defaults to one bar of `ts`.
+   *
+   * @defaultValue one bar of `ts`
+   */
   harmonicRhythm?: number;
-  /** End of the analyzed span in beats; defaults to the end of the last note. */
+  /**
+   * End of the analyzed span in beats; defaults to the end of the last note.
+   *
+   * @defaultValue the end of the last note
+   */
   totalBeats?: number;
 };
 
-/** The result of {@link chordTimelineFromNotes}. */
+/**
+ * The result of {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
 export type ChordTimelineResult = {
   /** The inferred timeline, with adjacent identical chords merged. */
   timeline: ChordTimeline;
@@ -266,10 +291,26 @@ function sameChord(a: Chord, b: Chord): boolean {
  * the fraction of the window weight explained by chord tones, reduced when the
  * match is inexact, and duration-weighted across merged windows.
  *
+ * Notes with a zero or negative duration never sound, so they are dropped at
+ * ingest: they contribute to neither the key inference, the span, nor any
+ * window's histogram.
+ *
  * @param notes The notes to analyze (any number of tracks, flattened).
  * @param opts Analysis options; see {@link ChordTimelineOptions}.
  * @returns The inferred timeline, the key used, and per-segment confidences.
  * @throws If `harmonicRhythm` is not positive.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 }, // C
+ *   { pitch: 64, startBeat: 0, durationBeat: 2 }, // E
+ *   { pitch: 67, startBeat: 0, durationBeat: 2 }, // G
+ * ];
+ * const { timeline, key } = chordTimelineFromNotes(notes);
+ * timeline.at(0); // the chord inferred over beat 0, or null
+ * ```
+ * @category Arrangement & Analysis
  */
 export function chordTimelineFromNotes(
   notes: NoteEvent[],
@@ -280,9 +321,11 @@ export function chordTimelineFromNotes(
   if (!(harmonicRhythm > 0)) {
     throw new Error(`Invalid harmonic rhythm: ${harmonicRhythm}`);
   }
-  const lastNoteEnd = notes.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
+  // Zero/negative-length notes never sound; drop them before any inference.
+  const sounding = notes.filter((note) => note.durationBeat > 0);
+  const lastNoteEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
   const totalBeats = opts.totalBeats ?? lastNoteEnd;
-  const key = opts.key ?? detectKey(notes.map((n) => n.pitch))[0]?.key ?? majorKey(0);
+  const key = opts.key ?? detectKey(sounding.map((n) => n.pitch))[0]?.key ?? majorKey(0);
 
   const segments: ChordSegment[] = [];
   const segmentConfidence: number[] = [];
@@ -290,7 +333,7 @@ export function chordTimelineFromNotes(
   for (let i = 0; i < windowCount; i += 1) {
     const start = i * harmonicRhythm;
     const end = Math.min(start + harmonicRhythm, totalBeats);
-    const inferred = analyzeWindow(notes, start, end, ts, key);
+    const inferred = analyzeWindow(sounding, start, end, ts, key);
     if (!inferred) {
       continue;
     }
@@ -316,7 +359,11 @@ export function chordTimelineFromNotes(
   };
 }
 
-/** A cadence found between two consecutive timeline segments. */
+/**
+ * A cadence found between two consecutive timeline segments.
+ *
+ * @category Arrangement & Analysis
+ */
 export type CadenceHit = {
   /** The beat where the cadence arrives (the second chord's onset). */
   atBeat: number;
@@ -328,12 +375,25 @@ export type CadenceHit = {
 /**
  * Find cadences between consecutive segments of a chord timeline.
  *
- * Each adjacent segment pair is classified with {@link detectCadence}; pairs
- * forming no cadence are skipped.
+ * Each temporally adjacent segment pair is classified with
+ * {@link detectCadence}; pairs forming no cadence are skipped. Segments
+ * separated by a gap (a rest in the timeline) are not a chord-to-chord
+ * progression, so they are never paired.
  *
  * @param timeline The chord timeline to scan.
  * @param key The prevailing key.
  * @returns The cadences found, in time order.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes, detectCadences } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 67, startBeat: 0, durationBeat: 4 }, // G, a dominant
+ *   { pitch: 60, startBeat: 4, durationBeat: 4 }, // C, the tonic
+ * ];
+ * const { timeline, key } = chordTimelineFromNotes(notes);
+ * const cadences = detectCadences(timeline, key);
+ * ```
+ * @category Arrangement & Analysis
  */
 export function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceHit[] {
   const hits: CadenceHit[] = [];
@@ -343,6 +403,9 @@ export function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceH
     if (!prev || !cur) {
       continue;
     }
+    if (Math.abs(cur.startBeat - prev.endBeat) > EPS) {
+      continue; // A rest separates the chords; no cadential motion across it.
+    }
     const type = detectCadence(prev.chord, cur.chord, key);
     if (type !== null) {
       hits.push({ atBeat: cur.startBeat, type, from: prev.chord, to: cur.chord });

package/src/{analysis → analyze/voice}/index.ts

@@ -1,10 +1,17 @@
-import type { Chord } from '../chord/index.js';
-import { chordPitchClasses, chordToneRole } from '../chord/index.js';
-import { createsVerticalDissonance, isLeadingToneResolution } from '../counterpoint/index.js';
-import type { VoiceSnapshot } from '../safety/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { chordPitchClasses, chordToneRole } from '../../theory/chord/index.js';
+import {
+  createsVerticalDissonance,
+  isLeadingToneResolution,
+} from '../../theory/counterpoint/index.js';
+import type { VoiceSnapshot } from '../../theory/safety/index.js';
 
-/** A theory annotation attached to a note. */
+/**
+ * A theory annotation attached to a note.
+ *
+ * @category Arrangement & Analysis
+ */
 export type TheoryLabel =
   | { kind: 'chordTone'; role: 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' }
   | { kind: 'tension'; degree: 9 | 11 | 13 }
@@ -17,16 +24,27 @@ export type TheoryLabel =
   | { kind: 'needsResolution'; resolveTo: number }
   | { kind: 'leadingTone'; resolveTo: number };
 
-/** A note with its theory labels and a short rationale. */
+/**
+ * A note with its theory labels and a short rationale.
+ *
+ * @category Arrangement & Analysis
+ */
 export type AnalyzedNote = {
   noteId: number;
   labels: TheoryLabel[];
   rationale?: string;
 };
 
-/** A single note in a monophonic voice: a {@link NoteEvent} with a stable id. */
+/**
+ * A single note in a monophonic voice: a {@link NoteEvent} with a stable id.
+ *
+ * @category Arrangement & Analysis
+ */
 export type VoiceNote = NoteEvent & { id: number };
 
+/** Float tolerance for beat comparisons. */
+const EPS = 1e-9;
+
 function pitchClass(pitch: number): number {
   return ((Math.trunc(pitch) % 12) + 12) % 12;
 }
@@ -35,6 +53,26 @@ function intervalAboveRoot(pitch: number, chord: Chord): number {
   return (((pitchClass(pitch) - pitchClass(chord.rootPc)) % 12) + 12) % 12;
 }
 
+/**
+ * Interval class of a pitch above the actual sounding bass.
+ *
+ * Suspension figures (4-3, 7-6, 9-8) are named for the interval above the bass,
+ * not the chord root, so this prefers the lowest pitch among the other sounding
+ * voices when one lies below the note. Without a lower sounding voice it falls
+ * back to the chord's bass pitch class (or root in root position).
+ */
+function intervalAboveBass(pitch: number, others: VoiceSnapshot[], chord: Chord): number {
+  let bass = Number.POSITIVE_INFINITY;
+  for (const ov of others) {
+    bass = Math.min(bass, ov.pitch);
+  }
+  if (Number.isFinite(bass) && bass < pitch) {
+    return (((pitch - bass) % 12) + 12) % 12;
+  }
+  const ref = chord.bassPc ?? chord.rootPc;
+  return (((pitchClass(pitch) - pitchClass(ref)) % 12) + 12) % 12;
+}
+
 /**
  * Map an interval class above the root to its extended-tension scale degree:
  * a flat/natural ninth (1 or 2) to 9, an eleventh (5 or 6) to 11, and a
@@ -59,6 +97,10 @@ function isStep(a: number, b: number): boolean {
   return d === 1 || d === 2;
 }
 
+/**
+ * Classify a suspension figure from the interval class above the sounding bass
+ * (`ic`) and the resolution direction (`delta`, positive when resolving upward).
+ */
 function suspensionType(ic: number, delta: number): TheoryLabel & { kind: 'suspension' } {
   let type: 'sus4-3' | 'sus7-6' | 'sus9-8' | 'sus2-3';
   if (delta > 0) {
@@ -92,11 +134,30 @@ function stepResolution(pitch: number, chord: Chord): number | undefined {
  * avoid, or an unresolved-dissonance label. Leading-tone resolutions are noted
  * additionally.
  *
+ * The voice is expected to be monophonic (one note at a time). Notes sharing an
+ * onset are treated as simultaneous cluster members, not melodic neighbors, so
+ * they receive no melodic labels (suspension, passing, neighbor, anticipation,
+ * escape) — only harmonic ones. Callers with truly polyphonic material should
+ * split it into monophonic sub-voices first, as `analyzeArrangement` does.
+ *
  * @param voice The monophonic voice, in time order.
  * @param chordAtBeat Chord sounding at a given beat, or null.
  * @param key Key context for leading-tone detection.
  * @param otherVoicesAtBeat Other sounding voices at a given beat.
  * @returns One annotation per input note.
+ * @example
+ * ```ts
+ * import { analyzeVoice, makeChord, majorKey } from '@libraz/libcantus';
+ * const voice = [
+ *   { id: 0, pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { id: 1, pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { id: 2, pitch: 64, startBeat: 2, durationBeat: 1 },
+ * ];
+ * const cMajor = makeChord(0, 'maj');
+ * const labels = analyzeVoice(voice, () => cMajor, majorKey(0), () => []);
+ * labels; // one AnalyzedNote per input note, in the same order
+ * ```
+ * @category Arrangement & Analysis
  */
 export function analyzeVoice(
   voice: VoiceNote[],
@@ -111,8 +172,15 @@ export function analyzeVoice(
     if (!note) {
       continue;
     }
-    const prev = i > 0 ? voice[i - 1] : undefined;
-    const next = i + 1 < voice.length ? voice[i + 1] : undefined;
+    const prevNote = i > 0 ? voice[i - 1] : undefined;
+    const nextNote = i + 1 < voice.length ? voice[i + 1] : undefined;
+    // A neighboring note sharing this note's onset is a simultaneous cluster
+    // member, not a melodic predecessor/successor; treating it as one would
+    // fabricate passing/suspension figures, so it is dropped here.
+    const prev =
+      prevNote !== undefined && prevNote.startBeat < note.startBeat - EPS ? prevNote : undefined;
+    const next =
+      nextNote !== undefined && nextNote.startBeat > note.startBeat + EPS ? nextNote : undefined;
     const chord = chordAtBeat(note.startBeat);
     const labels: TheoryLabel[] = [];
     const member = isChordMember(note.pitch, chord);
@@ -133,11 +201,12 @@ export function analyzeVoice(
       const prevChord = chordAtBeat(prev.startBeat);
       const prepared = prev.pitch === note.pitch && isChordMember(prev.pitch, prevChord);
       const resolves = isStep(next.pitch, note.pitch);
-      const verticallyDissonant = otherVoicesAtBeat(note.startBeat).some((ov) =>
+      const others = otherVoicesAtBeat(note.startBeat);
+      const verticallyDissonant = others.some((ov) =>
         createsVerticalDissonance(note.pitch, ov.pitch, true),
       );
       if (prepared && verticallyDissonant && resolves) {
-        const ic = intervalAboveRoot(note.pitch, chord);
+        const ic = intervalAboveBass(note.pitch, others, chord);
         const sus = suspensionType(ic, next.pitch - note.pitch);
         sus.resolveTo = next.pitch;
         labels.push(sus);

package/src/core/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Public API of the core layer. Re-exports every core-layer module;
+ * also available from the package root.
+ */
+export {
+  classifyInterval,
+  IntervalQuality,
+  isConsonantInterval,
+  isPerfectInterval,
+} from './interval/index.js';
+export type { BarPosition, TimeSignature } from './meter/index.js';
+export {
+  barPositionToBeat,
+  beatsPerBar,
+  beatToBarPosition,
+  formatTimeSignature,
+  isCompound,
+  isStrongBeat,
+  metricWeight,
+  parseTimeSignature,
+  pulsesPerBar,
+  tuplet,
+} from './meter/index.js';
+export type { Note as NoteData, SpelledInterval } from './pitch/index.js';
+export {
+  formatNote,
+  midiToNote,
+  noteToMidi,
+  noteToPitchClass,
+  parseNote,
+  spelledInterval,
+} from './pitch/index.js';
+export type { Rng } from './random/index.js';
+export { createRng } from './random/index.js';
+export type { Tuning } from './tuning/index.js';
+export {
+  centsBetweenFreq,
+  centsOfSteps,
+  edo,
+  frequencyOf,
+  JUST_RATIOS,
+  justDeviationCents,
+  nearestStep,
+  ratioToCents,
+  TWELVE_TET,
+} from './tuning/index.js';
+export type { KeyScale, NoteEvent } from './types.js';

package/src/{interval → core/interval}/index.ts

@@ -1,4 +1,8 @@
-/** Counterpoint classification of a harmonic interval. */
+/**
+ * Counterpoint classification of a harmonic interval.
+ *
+ * @category Pitch & Intervals
+ */
 export enum IntervalQuality {
   PerfectConsonance = 0,
   ImperfectConsonance = 1,
@@ -21,6 +25,14 @@ function simpleInterval(semitones: number): number {
  * @param semitones Interval size in semitones (may be negative or compound).
  * @param twoVoice When true, the perfect fourth is treated as dissonant.
  * @returns The counterpoint quality of the interval.
+ * @example
+ * ```ts
+ * import { classifyInterval, IntervalQuality } from '@libraz/libcantus';
+ * classifyInterval(7); // IntervalQuality.PerfectConsonance
+ * classifyInterval(5); // IntervalQuality.Dissonance (two-voice)
+ * classifyInterval(5, false); // IntervalQuality.ImperfectConsonance
+ * ```
+ * @category Pitch & Intervals
  */
 export function classifyInterval(semitones: number, twoVoice = true): IntervalQuality {
   const pc = simpleInterval(semitones);
@@ -41,6 +53,7 @@ export function classifyInterval(semitones: number, twoVoice = true): IntervalQu
  *
  * @param semitones Interval size in semitones (may be negative or compound).
  * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.
+ * @category Pitch & Intervals
  */
 export function isPerfectInterval(semitones: number): boolean {
   const pc = simpleInterval(semitones);
@@ -57,6 +70,7 @@ export function isPerfectInterval(semitones: number): boolean {
  * @param semitones Interval size in semitones (may be negative or compound).
  * @param twoVoice When true, the perfect fourth is treated as dissonant.
  * @returns True if the interval is consonant in the given context.
+ * @category Pitch & Intervals
  */
 export function isConsonantInterval(semitones: number, twoVoice = true): boolean {
   const pc = simpleInterval(semitones);

package/src/{meter → core/meter}/index.ts

@@ -6,13 +6,31 @@
  * 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. */
+/**
+ * A time signature as a numerator over a note-value denominator.
+ *
+ * @category Rhythm & Meter
+ */
 export 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
+   * {@link pulsesPerBar}. 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. */
+/**
+ * A position expressed as a bar index and a quarter-note offset within the bar.
+ *
+ * @category Rhythm & Meter
+ */
 export type BarPosition = {
   bar: number;
   /** Quarter-note offset from the start of the bar. */
@@ -36,6 +54,12 @@ function isMultiple(value: number, unit: number): boolean {
  * @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
  */
 export function parseTimeSignature(text: string): TimeSignature {
   const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(text);
@@ -50,7 +74,11 @@ export function parseTimeSignature(text: string): TimeSignature {
   return { numerator, denominator };
 }
 
-/** Render a time signature as `"n/d"`. */
+/**
+ * Render a time signature as `"n/d"`.
+ *
+ * @category Rhythm & Meter
+ */
 export function formatTimeSignature(ts: TimeSignature): string {
   return `${ts.numerator}/${ts.denominator}`;
 }
@@ -63,6 +91,7 @@ export function formatTimeSignature(ts: TimeSignature): string {
  *
  * @param ts The time signature.
  * @returns True for compound meters.
+ * @category Rhythm & Meter
  */
 export function isCompound(ts: TimeSignature): boolean {
   return ts.numerator % 3 === 0 && ts.numerator > 3;
@@ -78,6 +107,7 @@ function unitBeats(ts: TimeSignature): number {
  *
  * @param ts The time signature.
  * @returns The bar length in quarter notes.
+ * @category Rhythm & Meter
  */
 export function beatsPerBar(ts: TimeSignature): number {
   return ts.numerator * unitBeats(ts);
@@ -92,19 +122,63 @@ function pulseBeats(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
  */
 export function pulsesPerBar(ts: TimeSignature): number {
   return beatsPerBar(ts) / pulseBeats(ts);
 }
 
+/**
+ * Whether `grouping` is a valid additive grouping for a bar of `pulses` main
+ * pulses: a non-empty list of positive integers summing to `pulses`.
+ */
+function isValidGrouping(grouping: number[], pulses: number): boolean {
+  if (grouping.length === 0) {
+    return false;
+  }
+  let sum = 0;
+  for (const g of grouping) {
+    if (!Number.isInteger(g) || g <= 0) {
+      return false;
+    }
+    sum += g;
+  }
+  return sum === pulses;
+}
+
+/** Whether `pulseIndex` is the head pulse of one of the additive groups. */
+function isGroupHead(grouping: number[], pulseIndex: number): boolean {
+  let acc = 0;
+  for (const g of grouping) {
+    if (acc === pulseIndex) {
+      return true;
+    }
+    acc += g;
+  }
+  return false;
+}
+
 /**
  * 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
  */
 export function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition {
   const barLen = beatsPerBar(ts);
@@ -119,6 +193,7 @@ export function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): Ba
  * @param pos The bar position.
  * @param ts The time signature.
  * @returns The absolute position in quarter-note beats.
+ * @category Rhythm & Meter
  */
 export function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number {
   return pos.bar * beatsPerBar(ts) + pos.beat;
@@ -126,12 +201,28 @@ export 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 (the bar's midpoint in even
- * meters), 1 any other main pulse, and 0 an off-pulse subdivision.
+ * 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 `ts.grouping` is present but is not a positive-integer list
+ *   summing to {@link pulsesPerBar}.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * metricWeight(0, ts); // 3 (the downbeat)
+ * ```
+ * @category Rhythm & Meter
  */
 export function metricWeight(beatInQuarters: number, ts: TimeSignature): number {
   const { beat } = beatToBarPosition(beatInQuarters, ts);
@@ -144,6 +235,16 @@ export function metricWeight(beatInQuarters: number, ts: TimeSignature): number
   if (pulseIndex === 0) {
     return 3;
   }
+  const grouping = ts.grouping;
+  if (grouping !== undefined) {
+    if (!isValidGrouping(grouping, pulses)) {
+      throw new Error(
+        `Invalid grouping [${grouping.join(', ')}] for ${formatTimeSignature(ts)}: ` +
+          `entries must be positive integers summing to ${pulses}`,
+      );
+    }
+    return isGroupHead(grouping, pulseIndex) ? 2 : 1;
+  }
   if (pulses % 2 === 0 && pulseIndex === pulses / 2) {
     return 2;
   }
@@ -157,6 +258,7 @@ export function metricWeight(beatInQuarters: number, ts: TimeSignature): number
  * @param beatInQuarters Absolute or in-bar quarter-note position.
  * @param ts The time signature.
  * @returns True on strong beats.
+ * @category Rhythm & Meter
  */
 export function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean {
   return metricWeight(beatInQuarters, ts) >= 2;
@@ -170,6 +272,7 @@ export function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean
  * @param count Number of equal parts.
  * @returns `count` equal durations summing to `totalBeats`.
  * @throws If `count` is not a positive integer.
+ * @category Rhythm & Meter
  */
 export function tuplet(totalBeats: number, count: number): number[] {
   if (!Number.isInteger(count) || count <= 0) {