@libraz/libcantus-wasm 0.0.0-stage → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,514 @@
1
+ import { P as ParseResult } from './index-C9MYbuKS.js';
2
+
3
+ /**
4
+ * Meter arithmetic shared by the meter module and the validation guards.
5
+ *
6
+ * These helpers never validate: they are the single definition of how a time
7
+ * signature is read, so the guard that rejects a malformed signature and the
8
+ * functions that use a validated one cannot drift apart. Everything here is
9
+ * integer arithmetic on the numerator, so a bar's pulse count is exact rather
10
+ * than the result of dividing two floats.
11
+ */
12
+
13
+ /**
14
+ * A meter in the plain data the library reads it as: one signature, or the map
15
+ * of a piece that changes meter.
16
+ *
17
+ * What {@link MeterLike} resolves to, and the type every function below the
18
+ * entry points works in — the text form is read once, at the boundary.
19
+ *
20
+ * @category Rhythm & Meter
21
+ */
22
+ type MeterData = TimeSignature | MeterMap;
23
+
24
+ /**
25
+ * Meter and time signatures: bar/beat arithmetic, simple vs. compound meters,
26
+ * metric-accent hierarchy, and tuplet subdivision.
27
+ *
28
+ * Positions and durations are measured in quarter-note beats, matching the rest
29
+ * of the library's beat convention (four quarter-note beats per bar in 4/4).
30
+ * Beat 0 is the first downbeat, so a pickup sounds at negative beats, and a
31
+ * piece that changes meter is described by a {@link MeterMap} rather than by
32
+ * one signature.
33
+ */
34
+
35
+ /**
36
+ * A time signature as a numerator over a note-value denominator.
37
+ *
38
+ * @category Rhythm & Meter
39
+ */
40
+ type TimeSignature = {
41
+ numerator: number;
42
+ denominator: number;
43
+ /**
44
+ * Optional grouping of the bar into felt beats, as positive integers. The
45
+ * entries are group lengths, written either in the meter's main pulses —
46
+ * `[2, 2, 3]` for a 2+2+3 reading of 7/8, `[3, 2]` for 5/8 — or, for a
47
+ * compound numerator, in denominator units. They must sum to
48
+ * {@link pulsesPerBar} in the first spelling and to the numerator in the
49
+ * second; a pulse is one unit outside compound meters, where the two
50
+ * spellings coincide.
51
+ *
52
+ * A compound numerator accepts both readings, and the shape of the grouping
53
+ * says which is meant. Groups of nothing but threes spell the compound
54
+ * division itself, so 9/8 as `[3, 3, 3]` (equivalently `[1, 1, 1]`) is the
55
+ * ordinary three dotted-quarter pulses; any other grouping summing to the
56
+ * numerator reads additively, so 9/8 as `[2, 2, 2, 3]` is nine quaver pulses
57
+ * grouped aksak-fashion. {@link pulsesPerBar}, {@link pulseBeats} and
58
+ * {@link isCompound} follow whichever reading the grouping selects.
59
+ *
60
+ * The head pulse of each group other than the downbeat is a secondary strong
61
+ * pulse to {@link metricWeight}/{@link isStrongBeat}. A grouping whose groups
62
+ * are all the same length states no accent the meter does not already have,
63
+ * so it weighs exactly as an ungrouped bar does.
64
+ */
65
+ grouping?: number[];
66
+ };
67
+ /**
68
+ * One time signature and the beat at which it takes effect.
69
+ *
70
+ * @category Rhythm & Meter
71
+ */
72
+ type MeterChange = {
73
+ /** Absolute quarter-note beat the signature takes effect at. */
74
+ startBeat: number;
75
+ /** The signature in force from that beat until the next change. */
76
+ ts: TimeSignature;
77
+ };
78
+ /**
79
+ * A piece's meter over time: the signatures in force, in beat order.
80
+ *
81
+ * A meter change starts a new bar, so a span that does not divide evenly into
82
+ * its own bars ends with a short bar rather than spilling across the change.
83
+ * The first entry also governs everything before it, which is what reads a
84
+ * pickup written at negative beats in the signature the piece opens in.
85
+ *
86
+ * Beat 0 is the first downbeat here as everywhere else: the opening signature
87
+ * lays its bar lines from beat 0 whatever beat the first entry is written at, so
88
+ * a map opening at the pickup it covers numbers its bars exactly as the bare
89
+ * signature does. Every later entry starts a bar at the beat it takes effect.
90
+ * Bars are numbered so that the bar containing beat 0 is bar 0, so a pickup
91
+ * written as an entry of its own before a change at beat 0 is bar -1 all the
92
+ * same.
93
+ *
94
+ * Pass the whole piece with its map rather than one call per meter span: a
95
+ * split call cannot see a voice move or a key region that crosses the change.
96
+ *
97
+ * @category Rhythm & Meter
98
+ */
99
+ type MeterMap = MeterChange[];
100
+
101
+ /**
102
+ * Anything that names a meter: a signature text such as `'6/8'`, a plain
103
+ * {@link TimeSignature}, a full {@link MeterMap}, or a value that serializes to
104
+ * one of those such as the `Meter` class.
105
+ *
106
+ * Every meter-aware function takes this, so a piece in one meter reads as
107
+ * `'4/4'` and a piece that changes meter reads as the map, without the caller
108
+ * choosing a different function for each. Only a signature has a text form — a
109
+ * meter map is a run of changes and is given as the data it is.
110
+ *
111
+ * @category Rhythm & Meter
112
+ */
113
+ type MeterLike = string | TimeSignature | MeterMap | {
114
+ /** The meter data this value stands for. */
115
+ toJSON(): TimeSignature | MeterMap;
116
+ };
117
+ /**
118
+ * Resolve any meter-shaped value to the plain meter data the library reads.
119
+ *
120
+ * The counterpart of {@link toNoteData} for meters: an entry point takes
121
+ * whatever form the caller has — the signature a meter field holds, the data
122
+ * the meter module returns, the map of a piece that changes meter, or a `Meter`
123
+ * instance — and gets one of two shapes back. An instance is accepted through
124
+ * its `toJSON` method rather than by its type, so the core layer can read a
125
+ * class it cannot import.
126
+ *
127
+ * Text is read by {@link parseTimeSignature} and nothing else, so every entry
128
+ * point that takes a meter accepts exactly the signatures that parser accepts,
129
+ * the additive `'2+2+3/8'` included and nothing besides. A meter map has no text
130
+ * form — it is a run of changes, each with the beat it starts at — so text
131
+ * always names a single signature.
132
+ *
133
+ * @param value A signature text, a plain time signature, a meter map, or a
134
+ * value whose `toJSON` returns one of those.
135
+ * @param name What the meter is called in an error message, so a caller that
136
+ * holds several of them hears which one was malformed.
137
+ * @returns The validated signature, or the validated map, freshly allocated
138
+ * down to every grouping array — so a caller may keep and edit what it gets
139
+ * back without editing the meter it passed in, and without any two calls
140
+ * handing out the same object.
141
+ * @throws If the value names no meter, or the meter it names is malformed.
142
+ */
143
+ declare function toMeterData(value: MeterLike, name?: string): MeterData;
144
+ /**
145
+ * A position expressed as a bar index and a quarter-note offset within the bar.
146
+ *
147
+ * @category Rhythm & Meter
148
+ */
149
+ type BarPosition = {
150
+ /**
151
+ * 0-based bar index, counting the first full bar as 0.
152
+ * {@link formatBarPosition} renders it 1-based. A pickup sounds before that
153
+ * bar, so its notes report bar -1.
154
+ */
155
+ bar: number;
156
+ /**
157
+ * Quarter-note offset from the start of the bar — not the felt beat. In 6/8
158
+ * the second felt beat is at `beat: 1.5`; {@link barPositionToPulse} converts
159
+ * to felt-beat numbering.
160
+ */
161
+ beat: number;
162
+ };
163
+ /**
164
+ * Parse a time signature such as `"4/4"` or `"6/8"`, or the additive `"2+2+3/8"`.
165
+ *
166
+ * @param text The signature text.
167
+ * @returns The parsed time signature.
168
+ * @throws If the text is not `n/d` with positive integers, or names a signature
169
+ * the library rejects. Use {@link tryParseTimeSignature} where failure is
170
+ * ordinary, such as a meter field read on every keystroke.
171
+ * @example
172
+ * ```ts
173
+ * import { parseTimeSignature } from '@libraz/libcantus';
174
+ * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }
175
+ * ```
176
+ * @category Rhythm & Meter
177
+ */
178
+ declare function parseTimeSignature(text: string): TimeSignature;
179
+ /**
180
+ * Parse a time signature, reporting failure instead of throwing it.
181
+ *
182
+ * The same reading as {@link parseTimeSignature} — that function is this one
183
+ * with its error thrown — for the callers where text that does not parse yet is
184
+ * the normal state of the input rather than a fault.
185
+ *
186
+ * @param text The signature text.
187
+ * @returns The signature, or the error explaining why the text is not one.
188
+ * @example
189
+ * ```ts
190
+ * import { tryParseTimeSignature } from '@libraz/libcantus';
191
+ * const result = tryParseTimeSignature('7/8');
192
+ * result.ok ? result.value.numerator : result.error.message;
193
+ * ```
194
+ * @category Rhythm & Meter
195
+ */
196
+ declare function tryParseTimeSignature(text: string): ParseResult<TimeSignature>;
197
+ /**
198
+ * Render a time signature as `"n/d"`, or as `"a+b+c/d"` when it carries an
199
+ * additive grouping and `grouping` is requested.
200
+ *
201
+ * The additive form is what {@link parseTimeSignature} reads back, and it adds
202
+ * its terms to get the numerator — so only a grouping written in denominator
203
+ * units can be rendered that way. A grouping counted in main pulses whose groups
204
+ * are all the same length (9/8 as `[1, 1, 1]`, 12/8 as `[2, 2]`) states the
205
+ * division the bare signature already has, so it falls back to the plain form at
206
+ * no cost. One whose groups differ (12/8 as `[1, 1, 2]`) states an accent no
207
+ * signature text can carry, and asking for the additive form of it is refused
208
+ * rather than answered with a bar that weighs its pulses differently.
209
+ *
210
+ * The plain form drops the grouping, so a round trip through it reads 7/8 as
211
+ * flat rather than as 2+2+3; ask for the additive form to keep it.
212
+ *
213
+ * @param ts The time signature, in any form that names one; a meter map is
214
+ * rendered as the signature it opens in.
215
+ * @param opts Set `grouping: true` to render an additive grouping.
216
+ * @returns The formatted signature.
217
+ * @throws If `grouping: true` is asked of a grouping that no signature text can
218
+ * spell: one counted in main pulses, on a compound numerator, whose groups are
219
+ * not all the same length.
220
+ * @example
221
+ * ```ts
222
+ * import { formatTimeSignature } from '@libraz/libcantus';
223
+ * const aksak = { numerator: 7, denominator: 8, grouping: [2, 2, 3] };
224
+ * formatTimeSignature(aksak); // '7/8'
225
+ * formatTimeSignature(aksak, { grouping: true }); // '2+2+3/8'
226
+ * ```
227
+ * @category Rhythm & Meter
228
+ */
229
+ declare function formatTimeSignature(ts: MeterLike, opts?: {
230
+ grouping?: boolean;
231
+ }): string;
232
+ /**
233
+ * Whether a meter is compound: its main pulses each divide into three, as in
234
+ * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a
235
+ * multiple of three greater than three, independent of the denominator. Meters
236
+ * like 3/8 and 3/4 (simple triples, numerator 3) are not compound, and neither
237
+ * is a signature whose {@link TimeSignature.grouping} selects the additive
238
+ * reading (9/8 as 2+2+2+3).
239
+ *
240
+ * @param ts The time signature, in any form that names one; a meter map is read
241
+ * as the signature it opens in.
242
+ * @returns True for compound meters.
243
+ * @category Rhythm & Meter
244
+ */
245
+ declare function isCompound(ts: MeterLike): boolean;
246
+ /**
247
+ * Length of a bar in quarter-note beats.
248
+ *
249
+ * @param ts The time signature, in any form that names one; a meter map has no
250
+ * single bar length, so it is read as the signature it opens in. Ask
251
+ * {@link beatsPerBarAt} for the bar a given beat falls in.
252
+ * @returns The bar length in quarter notes.
253
+ * @example
254
+ * ```ts
255
+ * import { beatsPerBar } from '@libraz/libcantus';
256
+ * beatsPerBar('6/8'); // 3
257
+ * ```
258
+ * @category Rhythm & Meter
259
+ */
260
+ declare function beatsPerBar(ts: MeterLike): number;
261
+ /**
262
+ * The time signature in force at a beat.
263
+ *
264
+ * @param beatInQuarters Absolute position in quarter-note beats.
265
+ * @param meter A single signature, or the piece's meter map.
266
+ * @returns The signature governing that beat.
267
+ * @example
268
+ * ```ts
269
+ * import { meterAt, parseTimeSignature } from '@libraz/libcantus';
270
+ * const meters = [
271
+ * { startBeat: 0, ts: parseTimeSignature('4/4') },
272
+ * { startBeat: 8, ts: parseTimeSignature('3/4') },
273
+ * ];
274
+ * meterAt(9, meters); // { numerator: 3, denominator: 4 }
275
+ * ```
276
+ * @category Rhythm & Meter
277
+ */
278
+ declare function meterAt(beatInQuarters: number, meter: MeterLike): TimeSignature;
279
+ /**
280
+ * Absolute beat at which the bar containing `beatInQuarters` begins.
281
+ *
282
+ * @param beatInQuarters Absolute position in quarter-note beats.
283
+ * @param meter A single signature, or the piece's meter map.
284
+ * @returns The bar's first beat, negative inside a pickup.
285
+ * @category Rhythm & Meter
286
+ */
287
+ declare function barStartBeat(beatInQuarters: number, meter: MeterLike): number;
288
+ /**
289
+ * Bar index of a beat: 0 for the first full bar, negative inside a pickup.
290
+ *
291
+ * Bars accumulate across meter changes, so the bar after a 4/4-to-3/4 change is
292
+ * the next bar and not the first bar of a new count.
293
+ *
294
+ * @param beatInQuarters Absolute position in quarter-note beats.
295
+ * @param meter A single signature, or the piece's meter map.
296
+ * @returns The 0-based bar index.
297
+ * @example
298
+ * ```ts
299
+ * import { barIndexAt, parseTimeSignature } from '@libraz/libcantus';
300
+ * const meters = [
301
+ * { startBeat: 0, ts: parseTimeSignature('4/4') },
302
+ * { startBeat: 8, ts: parseTimeSignature('3/4') },
303
+ * ];
304
+ * barIndexAt(11, meters); // 3
305
+ * ```
306
+ * @category Rhythm & Meter
307
+ */
308
+ declare function barIndexAt(beatInQuarters: number, meter: MeterLike): number;
309
+ /**
310
+ * Length in quarter-note beats of the bar containing a beat.
311
+ *
312
+ * The meter-map counterpart of {@link beatsPerBar}, which answers for one
313
+ * signature and so cannot be asked about a piece that changes meter.
314
+ *
315
+ * The bar the beat is in, not the bar its signature nominally has: a change of
316
+ * meter starts a new bar, so a bar interrupted by one is shorter than its own
317
+ * signature says. Reading the signature's own length there would put the end of
318
+ * the bar past where the next one begins, and every span measured in bars from
319
+ * that point on would be counted against a bar length the music never had.
320
+ *
321
+ * @param beatInQuarters Absolute position in quarter-note beats.
322
+ * @param meter A single signature, or the piece's meter map.
323
+ * @returns The bar length in quarter notes.
324
+ * @category Rhythm & Meter
325
+ */
326
+ declare function beatsPerBarAt(beatInQuarters: number, meter: MeterLike): number;
327
+ /**
328
+ * Read the meter out of a pair of options that accept either form.
329
+ *
330
+ * Entry points take `meters` for a piece that changes meter and keep `ts` as
331
+ * sugar for a piece that does not, so this is the one place that resolves the
332
+ * pair — including the rule that naming both is an input error rather than one
333
+ * of them silently winning.
334
+ *
335
+ * @param opts The options carrying `ts`, `meters`, or neither.
336
+ * @param name What the options belong to, for the error message.
337
+ * @returns The meter map to analyse against, freshly allocated down to every
338
+ * signature and grouping array, so writing to it changes nothing another
339
+ * caller reads; 4/4 throughout when neither `ts` nor `meters` is given.
340
+ * @throws If both `ts` and `meters` are given, or the map is malformed.
341
+ * @example
342
+ * ```ts
343
+ * import { parseTimeSignature, resolveMeters } from '@libraz/libcantus';
344
+ * resolveMeters({ ts: parseTimeSignature('3/4') });
345
+ * // [{ startBeat: 0, ts: { numerator: 3, denominator: 4 } }]
346
+ * ```
347
+ * @category Rhythm & Meter
348
+ */
349
+ declare function resolveMeters(opts: {
350
+ ts?: MeterLike;
351
+ meters?: MeterLike;
352
+ }, name?: string): MeterMap;
353
+ /**
354
+ * Number of main pulses (felt beats) per bar: the numerator for simple meters,
355
+ * a third of it for compound meters.
356
+ *
357
+ * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses
358
+ * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and
359
+ * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set
360
+ * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
361
+ * group's head pulse.
362
+ *
363
+ * @param ts The time signature, in any form that names one; a meter map is read
364
+ * as the signature it opens in.
365
+ * @returns The pulse count per bar.
366
+ * @category Rhythm & Meter
367
+ */
368
+ declare function pulsesPerBar(ts: MeterLike): number;
369
+ /**
370
+ * Convert an absolute quarter-note position to a bar index and in-bar offset.
371
+ *
372
+ * @param beatInQuarters Absolute position in quarter-note beats.
373
+ * @param meter A single signature, or the piece's meter map.
374
+ * @returns The bar and in-bar quarter-note offset.
375
+ * @example
376
+ * ```ts
377
+ * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';
378
+ * const ts = parseTimeSignature('4/4');
379
+ * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }
380
+ * ```
381
+ * @category Rhythm & Meter
382
+ */
383
+ declare function beatToBarPosition(beatInQuarters: number, meter: MeterLike): BarPosition;
384
+ /**
385
+ * Length of one felt beat (main pulse) in quarter-note beats.
386
+ *
387
+ * A quarter note in simple meters, a dotted quarter in compound ones, and one
388
+ * denominator unit in an additive metre. Position displays, click tracks, and
389
+ * score export are all written against this length.
390
+ *
391
+ * @param ts The time signature, in any form that names one; a meter map is read
392
+ * as the signature it opens in.
393
+ * @returns The pulse length in quarter-note beats.
394
+ * @example
395
+ * ```ts
396
+ * import { pulseBeats } from '@libraz/libcantus';
397
+ * pulseBeats('6/8'); // 1.5
398
+ * ```
399
+ * @category Rhythm & Meter
400
+ */
401
+ declare function pulseBeats(ts: MeterLike): number;
402
+ /**
403
+ * The felt-beat number of a bar position, 1-based.
404
+ *
405
+ * {@link BarPosition.beat} is a quarter-note offset, so in 6/8 the second felt
406
+ * beat reads as 1.5. This is the number a musician says and a position display
407
+ * shows.
408
+ *
409
+ * @param pos The bar position.
410
+ * @param meter A single signature, or the piece's meter map.
411
+ * @returns The 1-based felt-beat number, fractional between pulses.
412
+ * @example
413
+ * ```ts
414
+ * import { barPositionToPulse, parseTimeSignature } from '@libraz/libcantus';
415
+ * barPositionToPulse({ bar: 0, beat: 1.5 }, parseTimeSignature('6/8')); // 2
416
+ * ```
417
+ * @category Rhythm & Meter
418
+ */
419
+ declare function barPositionToPulse(pos: BarPosition, meter: MeterLike): number;
420
+ /**
421
+ * Render an absolute position as the `bar.beat` a DAW or a score shows:
422
+ * 1-based bar, 1-based felt beat.
423
+ *
424
+ * The felt beats counted are the ones the bar actually has. A meter change
425
+ * starts a new bar, so the bar it interrupts is short, and a position that
426
+ * rounds past the end of a short bar reads as the downbeat of the next one
427
+ * rather than as a beat the bar never reached.
428
+ *
429
+ * @param beatInQuarters Absolute position in quarter-note beats.
430
+ * @param meter A single signature, or the piece's meter map.
431
+ * @param decimals Digits of the fractional beat to keep.
432
+ * @returns The formatted position in one of two forms: `bar.beat` on a felt
433
+ * beat, e.g. `'3.2'` for bar 3, felt beat 2; and `bar.beat+fraction` between
434
+ * felt beats, e.g. `'3.2+0.5'` halfway from the second felt beat to the third.
435
+ * A reader of these strings has to take both, since most onsets of an ordinary
436
+ * piece fall between pulses.
437
+ * @example
438
+ * ```ts
439
+ * import { formatBarPosition, parseTimeSignature } from '@libraz/libcantus';
440
+ * formatBarPosition(7.5, parseTimeSignature('6/8')); // '3.2'
441
+ * formatBarPosition(8.25, parseTimeSignature('6/8')); // '3.2+0.5'
442
+ * ```
443
+ * @category Rhythm & Meter
444
+ */
445
+ declare function formatBarPosition(beatInQuarters: number, meter: MeterLike, decimals?: number): string;
446
+ /**
447
+ * Convert a bar index and in-bar offset back to an absolute quarter-note
448
+ * position.
449
+ *
450
+ * @param pos The bar position.
451
+ * @param meter A single signature, or the piece's meter map.
452
+ * @returns The absolute position in quarter-note beats.
453
+ * @category Rhythm & Meter
454
+ */
455
+ declare function barPositionToBeat(pos: BarPosition, meter: MeterLike): number;
456
+ /**
457
+ * Metric weight of a position within its bar, on a 0–3 scale:
458
+ * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an
459
+ * off-pulse subdivision.
460
+ *
461
+ * The secondary strong pulse is the bar's midpoint in even simple/compound
462
+ * meters. For an additive/irregular meter with {@link TimeSignature.grouping}
463
+ * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the
464
+ * downbeat is the secondary strong pulse instead; without a grouping every
465
+ * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided
466
+ * pulses). A grouping of equal-length groups (9/8 as `[1, 1, 1]`, 4/4 as
467
+ * `[1, 1, 1, 1]`) states the division the meter already has, so it weighs as
468
+ * an ungrouped bar rather than accenting every group head.
469
+ *
470
+ * Given a meter map, the weight follows the signature in force at that beat, so
471
+ * beat 2 of a piece is a mid-bar accent in 4/4 and a plain main pulse in 3/4.
472
+ * The downbeat is beat 0 however much pickup precedes it, so a note in the
473
+ * pickup weighs as the upbeat it is rather than as a downbeat.
474
+ *
475
+ * @param beatInQuarters Absolute quarter-note position, or an in-bar offset
476
+ * when the meter is a single signature.
477
+ * @param meter A single signature, or the piece's meter map.
478
+ * @returns The metric weight (0–3).
479
+ * @throws If the meter is malformed, including a grouping that is not a
480
+ * positive-integer list summing to the pulse count or the numerator.
481
+ * @example
482
+ * ```ts
483
+ * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';
484
+ * const ts = parseTimeSignature('4/4');
485
+ * metricWeight(0, ts); // 3 (the downbeat)
486
+ * ```
487
+ * @category Rhythm & Meter
488
+ */
489
+ declare function metricWeight(beatInQuarters: number, meter: MeterLike): number;
490
+ /**
491
+ * Whether a position is metrically accented (weight 2 or more — a downbeat or a
492
+ * secondary strong pulse).
493
+ *
494
+ * @param beatInQuarters Absolute quarter-note position, or an in-bar offset
495
+ * when the meter is a single signature.
496
+ * @param meter A single signature, or the piece's meter map.
497
+ * @returns True on strong beats.
498
+ * @category Rhythm & Meter
499
+ */
500
+ declare function isStrongBeat(beatInQuarters: number, meter: MeterLike): boolean;
501
+ /**
502
+ * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note
503
+ * triplet is `tuplet(1, 3)`).
504
+ *
505
+ * @param totalBeats Total span in quarter-note beats.
506
+ * @param count Number of equal parts.
507
+ * @returns `count` equal durations summing to `totalBeats`.
508
+ * @throws If `count` is not a positive integer.
509
+ * @category Rhythm & Meter
510
+ */
511
+ declare function tuplet(totalBeats: number, count: number): number[];
512
+
513
+ export { 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 };
514
+ export type { BarPosition as B, MeterChange as M, TimeSignature as T, MeterData as a, MeterLike as b, MeterMap as c };
@@ -0,0 +1,64 @@
1
+ import { i as ChordToneRole, c as ChordLike } from './coerce-CUhHc3Tu.js';
2
+
3
+ /**
4
+ * Harmonic role a pitch plays within a chord.
5
+ *
6
+ * @category Functional Harmony
7
+ */
8
+ type HarmonyRole = ChordToneRole | 'tension' | 'doubling';
9
+ /**
10
+ * How firmly a pitch is locked to the chord's identity.
11
+ *
12
+ * - `identity`: moving it produces a different chord (the root).
13
+ * - `quality`: moving it flips the chord quality (the third).
14
+ * - `voicing`: it can move freely without changing chord identity or quality.
15
+ *
16
+ * @category Functional Harmony
17
+ */
18
+ type LockLevel = 'identity' | 'quality' | 'voicing';
19
+ /**
20
+ * A pitch's role, lock level, and owning chord.
21
+ *
22
+ * @category Functional Harmony
23
+ */
24
+ type VoicedRole = {
25
+ role: HarmonyRole;
26
+ lock: LockLevel;
27
+ belongsToChordId: number;
28
+ };
29
+ /**
30
+ * Classify a pitch's harmonic role and lock level within a chord.
31
+ *
32
+ * The role comes from the pitch's interval class above the chord root, read
33
+ * against the chord's own template: root (0), third (3/4), fifth (6/7/8),
34
+ * sixth or seventh (9/10/11). Every pitch the template does not claim is
35
+ * `'tension'` — including one that is simply foreign to the chord, which this
36
+ * single-pitch query cannot tell from a colour tone. The root locks the chord
37
+ * identity, the third locks its quality, and everything else is free voicing.
38
+ * Where a chord has no third, the tone standing in its place — the fourth of a
39
+ * `sus4`, the second of a `sus2`, the eleventh of an eleventh chord — takes the
40
+ * third's slot and is locked to `quality`, since moving it changes the chord.
41
+ * At most one interval class of a chord is ever reported as its third, so a
42
+ * consumer reading `lock: 'quality'` as "this tone identifies the chord" gets
43
+ * one answer rather than two. Detecting an octave doubling requires the
44
+ * surrounding voicing, which this query does not carry, so `'doubling'` is part
45
+ * of the type — the shared vocabulary of harmonic roles — but is never returned
46
+ * here.
47
+ *
48
+ * @param pitch MIDI pitch or bare pitch class.
49
+ * @param chord The chord providing the root reference, as a chord symbol, chord
50
+ * data, or a `Chord`.
51
+ * @param chordId Identifier stored on the result (defaults to 0).
52
+ * @returns The pitch's role, lock level, and owning chord id.
53
+ * @example
54
+ * ```ts
55
+ * import { roleOf, makeChord } from '@libraz/libcantus';
56
+ * roleOf(64, makeChord(0, 'maj')); // E over C major
57
+ * // { role: 'third', lock: 'quality', belongsToChordId: 0 }
58
+ * ```
59
+ * @category Functional Harmony
60
+ */
61
+ declare function roleOf(pitch: number, chord: ChordLike, chordId?: number): VoicedRole;
62
+
63
+ export { roleOf as r };
64
+ export type { HarmonyRole as H, LockLevel as L, VoicedRole as V };