@libraz/libcantus-wasm 0.0.0-stage → 1.4.1

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,66 @@
1
+ /**
2
+ * Counterpoint classification of a harmonic interval by consonance.
3
+ *
4
+ * Distinct from a spelled interval's quality label — see
5
+ * {@link IntervalQualityLabel}, which names the `'P'` / `'M'` / `'m'` / `'A'` /
6
+ * `'d'` spelling of an interval rather than how it sounds against another
7
+ * voice.
8
+ *
9
+ * @see {@link IntervalQualityLabel}
10
+ * @category Pitch & Intervals
11
+ */
12
+ declare enum ConsonanceClass {
13
+ PerfectConsonance = 0,
14
+ ImperfectConsonance = 1,
15
+ Dissonance = 2
16
+ }
17
+ /**
18
+ * Classify an interval for counterpoint evaluation.
19
+ *
20
+ * The interval is reduced modulo 12, so compound intervals classify as their
21
+ * simple equivalents. The perfect fourth (5) is context-dependent: with
22
+ * `twoVoice` (the default) it classifies as a dissonance, matching
23
+ * {@link isConsonantInterval}; otherwise it is an imperfect consonance.
24
+ *
25
+ * @param semitones Interval size in semitones (may be negative or compound).
26
+ * @param twoVoice When true, the perfect fourth is treated as dissonant.
27
+ * @returns The counterpoint quality of the interval.
28
+ * @example
29
+ * ```ts
30
+ * import { classifyInterval, ConsonanceClass } from '@libraz/libcantus';
31
+ * classifyInterval(7); // ConsonanceClass.PerfectConsonance
32
+ * classifyInterval(5); // ConsonanceClass.Dissonance (two-voice)
33
+ * classifyInterval(5, false); // ConsonanceClass.ImperfectConsonance
34
+ * ```
35
+ * @category Pitch & Intervals
36
+ */
37
+ declare function classifyInterval(semitones: number, twoVoice?: boolean): ConsonanceClass;
38
+ /**
39
+ * Test whether an interval is a perfect consonance: the unison/octave or the
40
+ * fifth.
41
+ *
42
+ * The perfect fourth is deliberately excluded. This is the predicate the
43
+ * parallel-motion rules are written against, where the fourth behaves as a
44
+ * dissonance between two voices; {@link classifyInterval} is the general
45
+ * classifier, and it treats the fourth as context-dependent.
46
+ *
47
+ * @param semitones Interval size in semitones (may be negative or compound).
48
+ * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.
49
+ * @category Pitch & Intervals
50
+ */
51
+ declare function isPerfectInterval(semitones: number): boolean;
52
+ /**
53
+ * Test whether an interval is consonant.
54
+ *
55
+ * The consonant set is {0, 3, 4, 5, 7, 8, 9} mod 12. In two-voice counterpoint
56
+ * the perfect fourth (5) is treated as a dissonance, so `twoVoice` set to true
57
+ * excludes it.
58
+ *
59
+ * @param semitones Interval size in semitones (may be negative or compound).
60
+ * @param twoVoice When true, the perfect fourth is treated as dissonant.
61
+ * @returns True if the interval is consonant in the given context.
62
+ * @category Pitch & Intervals
63
+ */
64
+ declare function isConsonantInterval(semitones: number, twoVoice?: boolean): boolean;
65
+
66
+ export { ConsonanceClass as C, isPerfectInterval as a, classifyInterval as c, isConsonantInterval as i };
@@ -0,0 +1,515 @@
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
+ /**
165
+ * Parse a time signature such as `"4/4"` or `"6/8"`, or the additive `"2+2+3/8"`.
166
+ *
167
+ * @param text The signature text.
168
+ * @returns The parsed time signature.
169
+ * @throws If the text is not `n/d` with positive integers, or names a signature
170
+ * the library rejects. Use {@link tryParseTimeSignature} where failure is
171
+ * ordinary, such as a meter field read on every keystroke.
172
+ * @example
173
+ * ```ts
174
+ * import { parseTimeSignature } from '@libraz/libcantus';
175
+ * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }
176
+ * ```
177
+ * @category Rhythm & Meter
178
+ */
179
+ declare function parseTimeSignature(text: string): TimeSignature;
180
+ /**
181
+ * Parse a time signature, reporting failure instead of throwing it.
182
+ *
183
+ * The same reading as {@link parseTimeSignature} — that function is this one
184
+ * with its error thrown — for the callers where text that does not parse yet is
185
+ * the normal state of the input rather than a fault.
186
+ *
187
+ * @param text The signature text.
188
+ * @returns The signature, or the error explaining why the text is not one.
189
+ * @example
190
+ * ```ts
191
+ * import { tryParseTimeSignature } from '@libraz/libcantus';
192
+ * const result = tryParseTimeSignature('7/8');
193
+ * result.ok ? result.value.numerator : result.error.message;
194
+ * ```
195
+ * @category Rhythm & Meter
196
+ */
197
+ declare function tryParseTimeSignature(text: string): ParseResult<TimeSignature>;
198
+ /**
199
+ * Render a time signature as `"n/d"`, or as `"a+b+c/d"` when it carries an
200
+ * additive grouping and `grouping` is requested.
201
+ *
202
+ * The additive form is what {@link parseTimeSignature} reads back, and it adds
203
+ * its terms to get the numerator — so only a grouping written in denominator
204
+ * units can be rendered that way. A grouping counted in main pulses whose groups
205
+ * are all the same length (9/8 as `[1, 1, 1]`, 12/8 as `[2, 2]`) states the
206
+ * division the bare signature already has, so it falls back to the plain form at
207
+ * no cost. One whose groups differ (12/8 as `[1, 1, 2]`) states an accent no
208
+ * signature text can carry, and asking for the additive form of it is refused
209
+ * rather than answered with a bar that weighs its pulses differently.
210
+ *
211
+ * The plain form drops the grouping, so a round trip through it reads 7/8 as
212
+ * flat rather than as 2+2+3; ask for the additive form to keep it.
213
+ *
214
+ * @param ts The time signature, in any form that names one; a meter map is
215
+ * rendered as the signature it opens in.
216
+ * @param opts Set `grouping: true` to render an additive grouping.
217
+ * @returns The formatted signature.
218
+ * @throws If `grouping: true` is asked of a grouping that no signature text can
219
+ * spell: one counted in main pulses, on a compound numerator, whose groups are
220
+ * not all the same length.
221
+ * @example
222
+ * ```ts
223
+ * import { formatTimeSignature } from '@libraz/libcantus';
224
+ * const aksak = { numerator: 7, denominator: 8, grouping: [2, 2, 3] };
225
+ * formatTimeSignature(aksak); // '7/8'
226
+ * formatTimeSignature(aksak, { grouping: true }); // '2+2+3/8'
227
+ * ```
228
+ * @category Rhythm & Meter
229
+ */
230
+ declare function formatTimeSignature(ts: MeterLike, opts?: {
231
+ grouping?: boolean;
232
+ }): string;
233
+ /**
234
+ * Whether a meter is compound: its main pulses each divide into three, as in
235
+ * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a
236
+ * multiple of three greater than three, independent of the denominator. Meters
237
+ * like 3/8 and 3/4 (simple triples, numerator 3) are not compound, and neither
238
+ * is a signature whose {@link TimeSignature.grouping} selects the additive
239
+ * reading (9/8 as 2+2+2+3).
240
+ *
241
+ * @param ts The time signature, in any form that names one; a meter map is read
242
+ * as the signature it opens in.
243
+ * @returns True for compound meters.
244
+ * @category Rhythm & Meter
245
+ */
246
+ declare function isCompound(ts: MeterLike): boolean;
247
+ /**
248
+ * Length of a bar in quarter-note beats.
249
+ *
250
+ * @param ts The time signature, in any form that names one; a meter map has no
251
+ * single bar length, so it is read as the signature it opens in. Ask
252
+ * {@link beatsPerBarAt} for the bar a given beat falls in.
253
+ * @returns The bar length in quarter notes.
254
+ * @example
255
+ * ```ts
256
+ * import { beatsPerBar } from '@libraz/libcantus';
257
+ * beatsPerBar('6/8'); // 3
258
+ * ```
259
+ * @category Rhythm & Meter
260
+ */
261
+ declare function beatsPerBar(ts: MeterLike): number;
262
+ /**
263
+ * The time signature in force at a beat.
264
+ *
265
+ * @param beatInQuarters Absolute position in quarter-note beats.
266
+ * @param meter A single signature, or the piece's meter map.
267
+ * @returns The signature governing that beat.
268
+ * @example
269
+ * ```ts
270
+ * import { meterAt, parseTimeSignature } from '@libraz/libcantus';
271
+ * const meters = [
272
+ * { startBeat: 0, ts: parseTimeSignature('4/4') },
273
+ * { startBeat: 8, ts: parseTimeSignature('3/4') },
274
+ * ];
275
+ * meterAt(9, meters); // { numerator: 3, denominator: 4 }
276
+ * ```
277
+ * @category Rhythm & Meter
278
+ */
279
+ declare function meterAt(beatInQuarters: number, meter: MeterLike): TimeSignature;
280
+ /**
281
+ * Absolute beat at which the bar containing `beatInQuarters` begins.
282
+ *
283
+ * @param beatInQuarters Absolute position in quarter-note beats.
284
+ * @param meter A single signature, or the piece's meter map.
285
+ * @returns The bar's first beat, negative inside a pickup.
286
+ * @category Rhythm & Meter
287
+ */
288
+ declare function barStartBeat(beatInQuarters: number, meter: MeterLike): number;
289
+ /**
290
+ * Bar index of a beat: 0 for the first full bar, negative inside a pickup.
291
+ *
292
+ * Bars accumulate across meter changes, so the bar after a 4/4-to-3/4 change is
293
+ * the next bar and not the first bar of a new count.
294
+ *
295
+ * @param beatInQuarters Absolute position in quarter-note beats.
296
+ * @param meter A single signature, or the piece's meter map.
297
+ * @returns The 0-based bar index.
298
+ * @example
299
+ * ```ts
300
+ * import { barIndexAt, parseTimeSignature } from '@libraz/libcantus';
301
+ * const meters = [
302
+ * { startBeat: 0, ts: parseTimeSignature('4/4') },
303
+ * { startBeat: 8, ts: parseTimeSignature('3/4') },
304
+ * ];
305
+ * barIndexAt(11, meters); // 3
306
+ * ```
307
+ * @category Rhythm & Meter
308
+ */
309
+ declare function barIndexAt(beatInQuarters: number, meter: MeterLike): number;
310
+ /**
311
+ * Length in quarter-note beats of the bar containing a beat.
312
+ *
313
+ * The meter-map counterpart of {@link beatsPerBar}, which answers for one
314
+ * signature and so cannot be asked about a piece that changes meter.
315
+ *
316
+ * The bar the beat is in, not the bar its signature nominally has: a change of
317
+ * meter starts a new bar, so a bar interrupted by one is shorter than its own
318
+ * signature says. Reading the signature's own length there would put the end of
319
+ * the bar past where the next one begins, and every span measured in bars from
320
+ * that point on would be counted against a bar length the music never had.
321
+ *
322
+ * @param beatInQuarters Absolute position in quarter-note beats.
323
+ * @param meter A single signature, or the piece's meter map.
324
+ * @returns The bar length in quarter notes.
325
+ * @category Rhythm & Meter
326
+ */
327
+ declare function beatsPerBarAt(beatInQuarters: number, meter: MeterLike): number;
328
+ /**
329
+ * Read the meter out of a pair of options that accept either form.
330
+ *
331
+ * Entry points take `meters` for a piece that changes meter and keep `ts` as
332
+ * sugar for a piece that does not, so this is the one place that resolves the
333
+ * pair — including the rule that naming both is an input error rather than one
334
+ * of them silently winning.
335
+ *
336
+ * @param opts The options carrying `ts`, `meters`, or neither.
337
+ * @param name What the options belong to, for the error message.
338
+ * @returns The meter map to analyse against, freshly allocated down to every
339
+ * signature and grouping array, so writing to it changes nothing another
340
+ * caller reads; 4/4 throughout when neither `ts` nor `meters` is given.
341
+ * @throws If both `ts` and `meters` are given, or the map is malformed.
342
+ * @example
343
+ * ```ts
344
+ * import { parseTimeSignature, resolveMeters } from '@libraz/libcantus';
345
+ * resolveMeters({ ts: parseTimeSignature('3/4') });
346
+ * // [{ startBeat: 0, ts: { numerator: 3, denominator: 4 } }]
347
+ * ```
348
+ * @category Rhythm & Meter
349
+ */
350
+ declare function resolveMeters(opts: {
351
+ ts?: MeterLike;
352
+ meters?: MeterLike;
353
+ }, name?: string): MeterMap;
354
+ /**
355
+ * Number of main pulses (felt beats) per bar: the numerator for simple meters,
356
+ * a third of it for compound meters.
357
+ *
358
+ * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses
359
+ * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and
360
+ * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set
361
+ * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
362
+ * group's head pulse.
363
+ *
364
+ * @param ts The time signature, in any form that names one; a meter map is read
365
+ * as the signature it opens in.
366
+ * @returns The pulse count per bar.
367
+ * @category Rhythm & Meter
368
+ */
369
+ declare function pulsesPerBar(ts: MeterLike): number;
370
+ /**
371
+ * Convert an absolute quarter-note position to a bar index and in-bar offset.
372
+ *
373
+ * @param beatInQuarters Absolute position in quarter-note beats.
374
+ * @param meter A single signature, or the piece's meter map.
375
+ * @returns The bar and in-bar quarter-note offset.
376
+ * @example
377
+ * ```ts
378
+ * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';
379
+ * const ts = parseTimeSignature('4/4');
380
+ * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }
381
+ * ```
382
+ * @category Rhythm & Meter
383
+ */
384
+ declare function beatToBarPosition(beatInQuarters: number, meter: MeterLike): BarPosition;
385
+ /**
386
+ * Length of one felt beat (main pulse) in quarter-note beats.
387
+ *
388
+ * A quarter note in simple meters, a dotted quarter in compound ones, and one
389
+ * denominator unit in an additive metre. Position displays, click tracks, and
390
+ * score export are all written against this length.
391
+ *
392
+ * @param ts The time signature, in any form that names one; a meter map is read
393
+ * as the signature it opens in.
394
+ * @returns The pulse length in quarter-note beats.
395
+ * @example
396
+ * ```ts
397
+ * import { pulseBeats } from '@libraz/libcantus';
398
+ * pulseBeats('6/8'); // 1.5
399
+ * ```
400
+ * @category Rhythm & Meter
401
+ */
402
+ declare function pulseBeats(ts: MeterLike): number;
403
+ /**
404
+ * The felt-beat number of a bar position, 1-based.
405
+ *
406
+ * {@link BarPosition.beat} is a quarter-note offset, so in 6/8 the second felt
407
+ * beat reads as 1.5. This is the number a musician says and a position display
408
+ * shows.
409
+ *
410
+ * @param pos The bar position.
411
+ * @param meter A single signature, or the piece's meter map.
412
+ * @returns The 1-based felt-beat number, fractional between pulses.
413
+ * @example
414
+ * ```ts
415
+ * import { barPositionToPulse, parseTimeSignature } from '@libraz/libcantus';
416
+ * barPositionToPulse({ bar: 0, beat: 1.5 }, parseTimeSignature('6/8')); // 2
417
+ * ```
418
+ * @category Rhythm & Meter
419
+ */
420
+ declare function barPositionToPulse(pos: BarPosition, meter: MeterLike): number;
421
+ /**
422
+ * Render an absolute position as the `bar.beat` a DAW or a score shows:
423
+ * 1-based bar, 1-based felt beat.
424
+ *
425
+ * The felt beats counted are the ones the bar actually has. A meter change
426
+ * starts a new bar, so the bar it interrupts is short, and a position that
427
+ * rounds past the end of a short bar reads as the downbeat of the next one
428
+ * rather than as a beat the bar never reached.
429
+ *
430
+ * @param beatInQuarters Absolute position in quarter-note beats.
431
+ * @param meter A single signature, or the piece's meter map.
432
+ * @param decimals Digits of the fractional beat to keep.
433
+ * @returns The formatted position in one of two forms: `bar.beat` on a felt
434
+ * beat, e.g. `'3.2'` for bar 3, felt beat 2; and `bar.beat+fraction` between
435
+ * felt beats, e.g. `'3.2+0.5'` halfway from the second felt beat to the third.
436
+ * A reader of these strings has to take both, since most onsets of an ordinary
437
+ * piece fall between pulses.
438
+ * @example
439
+ * ```ts
440
+ * import { formatBarPosition, parseTimeSignature } from '@libraz/libcantus';
441
+ * formatBarPosition(7.5, parseTimeSignature('6/8')); // '3.2'
442
+ * formatBarPosition(8.25, parseTimeSignature('6/8')); // '3.2+0.5'
443
+ * ```
444
+ * @category Rhythm & Meter
445
+ */
446
+ declare function formatBarPosition(beatInQuarters: number, meter: MeterLike, decimals?: number): string;
447
+ /**
448
+ * Convert a bar index and in-bar offset back to an absolute quarter-note
449
+ * position.
450
+ *
451
+ * @param pos The bar position.
452
+ * @param meter A single signature, or the piece's meter map.
453
+ * @returns The absolute position in quarter-note beats.
454
+ * @category Rhythm & Meter
455
+ */
456
+ declare function barPositionToBeat(pos: BarPosition, meter: MeterLike): number;
457
+ /**
458
+ * Metric weight of a position within its bar, on a 0–3 scale:
459
+ * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an
460
+ * off-pulse subdivision.
461
+ *
462
+ * The secondary strong pulse is the bar's midpoint in even simple/compound
463
+ * meters. For an additive/irregular meter with {@link TimeSignature.grouping}
464
+ * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the
465
+ * downbeat is the secondary strong pulse instead; without a grouping every
466
+ * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided
467
+ * pulses). A grouping of equal-length groups (9/8 as `[1, 1, 1]`, 4/4 as
468
+ * `[1, 1, 1, 1]`) states the division the meter already has, so it weighs as
469
+ * an ungrouped bar rather than accenting every group head.
470
+ *
471
+ * Given a meter map, the weight follows the signature in force at that beat, so
472
+ * beat 2 of a piece is a mid-bar accent in 4/4 and a plain main pulse in 3/4.
473
+ * The downbeat is beat 0 however much pickup precedes it, so a note in the
474
+ * pickup weighs as the upbeat it is rather than as a downbeat.
475
+ *
476
+ * @param beatInQuarters Absolute quarter-note position, or an in-bar offset
477
+ * when the meter is a single signature.
478
+ * @param meter A single signature, or the piece's meter map.
479
+ * @returns The metric weight (0–3).
480
+ * @throws If the meter is malformed, including a grouping that is not a
481
+ * positive-integer list summing to the pulse count or the numerator.
482
+ * @example
483
+ * ```ts
484
+ * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';
485
+ * const ts = parseTimeSignature('4/4');
486
+ * metricWeight(0, ts); // 3 (the downbeat)
487
+ * ```
488
+ * @category Rhythm & Meter
489
+ */
490
+ declare function metricWeight(beatInQuarters: number, meter: MeterLike): number;
491
+ /**
492
+ * Whether a position is metrically accented (weight 2 or more — a downbeat or a
493
+ * secondary strong pulse).
494
+ *
495
+ * @param beatInQuarters Absolute quarter-note position, or an in-bar offset
496
+ * when the meter is a single signature.
497
+ * @param meter A single signature, or the piece's meter map.
498
+ * @returns True on strong beats.
499
+ * @category Rhythm & Meter
500
+ */
501
+ declare function isStrongBeat(beatInQuarters: number, meter: MeterLike): boolean;
502
+ /**
503
+ * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note
504
+ * triplet is `tuplet(1, 3)`).
505
+ *
506
+ * @param totalBeats Total span in quarter-note beats.
507
+ * @param count Number of equal parts.
508
+ * @returns `count` equal durations summing to `totalBeats`.
509
+ * @throws If `count` is not a positive integer.
510
+ * @category Rhythm & Meter
511
+ */
512
+ declare function tuplet(totalBeats: number, count: number): number[];
513
+
514
+ 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 };
515
+ export type { BarPosition as B, MeterChange as M, TimeSignature as T, MeterData as a, MeterLike as b, MeterMap as c };
@@ -0,0 +1,17 @@
1
+ export { A as ARTICULATIONS, a as Articulation, B as BudgetExceededError, I as IntervalData, b as IntervalLike, c as IntervalQualityLabel, d as InvalidInputError, K as KeyName, e as KeyScale, L as LibcantusError, f as LibcantusErrorCode, N as NoSolutionError, g as NoteData, h as NoteEvent, i as NoteLike, j as NoteNameOptions, k as NoteNameSystem, P as ParseResult, S as SpelledInterval, l as detectNoteNameSystem, m as diatonicLetterOf, n as formatKeyName, o as formatNote, p as intervalSemitones, q as isLibcantusError, r as midiToNote, s as naturalPitchClassOf, t as noteToMidi, u as noteToPitchClass, v as parseInterval, w as parseKeyName, x as parseNote, y as pitchClassOf, z as spelledInterval, C as toNoteData, D as toSpelledInterval, E as transposeByInterval, F as transposeNote, G as tryParseInterval, H as tryParseKeyName, J as tryParseNote } from './index-C9MYbuKS.js';
2
+ export { D as DurationData, I as IndexedNoteEvent, J as JUST_RATIOS, N as NOTE_VALUES, a as NoteEventIndex, b as NoteEventIndexOptions, c as NotePlacement, d as NoteValue, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, g as PlayabilityReport, S as SpelledDuration, T as TWELVE_TET, h as TempoEvent, i as TempoMap, j as TuningTable, k as Tuplet, l as beatsToDuration, m as beatsToSeconds, n as beatsToTicks, o as beatsToTiedDurations, p as centsBetweenFreq, q as centsFromNearestStep, r as centsOfSteps, s as centsToRatio, t as createNoteEventIndex, u as durationToBeats, v as durationToSeconds, w as edo, x as frequencyOf, y as justDeviationCents, z as nearestStep, A as playability, B as ratioToCents, C as secondsToBeats, E as stepOf, F as stepsOfCents, G as tempoAt, H as ticksToBeats } from './index-Cbs3SQe9.js';
3
+ export { I as InstrumentProfile, a as InstrumentProfileCommon, b as InstrumentProfileLike, L as LIMBS, c as Limb, P as PercussionProfile, d as PositionalRng, S as SeedPath, e as StringFingering, f as StringedProfile, V as ValidatedPercussionProfile, g as ValidatedProfile, h as ValidatedStringedProfile, i as canSound, j as createPositionalRng, k as deriveSeed, l as fingeringsFor, m as foldIntoRange, n as includeAt, o as instrumentRange, t as toInstrumentProfile, p as toStringedProfile } from './positional-DLnfUgqG.js';
4
+ export { ALGORITHM_VERSION, BASS_4_STRING, BASS_5_STRING, DEFAULT_GENERATION_BUDGET, GUITAR_DROP_D, GUITAR_STANDARD, MIN_ALGORITHM_VERSION, NoteEventAssertOptions, Rng, assertDegree, assertFiniteNumber, assertFiniteSemitones, assertGenerationBudget, assertInteger, assertMeterMap, assertMidiPitch, assertNoteEvent, assertNoteEvents, assertOneOf, assertPositiveInt, assertRange, assertTimeSignature, clampToMidi, createRng, dropSilentNotes, resolveAlgorithmVersion, soundingNotesOnly } from './core/index.js';
5
+ export { B as BarPosition, M as MeterChange, a as MeterData, b as MeterLike, c as MeterMap, T as TimeSignature, d as barIndexAt, e as barPositionToBeat, f as barPositionToPulse, g as barStartBeat, h as beatToBarPosition, i as beatsPerBar, j as beatsPerBarAt, k as formatBarPosition, l as formatTimeSignature, m as isCompound, n as isStrongBeat, o as meterAt, p as metricWeight, q as parseTimeSignature, r as pulseBeats, s as pulsesPerBar, t as resolveMeters, u as toMeterData, v as tryParseTimeSignature, w as tuplet } from './index-wE8SecK5.js';
6
+ export { A as Alteration, a as AlteredDegree, C as ChordBase, b as ChordData, c as ChordLike, d as ChordQuality, e as ChordSegment, f as ChordSeventh, g as ChordSpan, h as ChordSpec, i as ChordToneRole, E as EvaluateSafetyOptions, K as KeyLike, j as KeyRelation, k as KeyVariant, N as NoteSafety, P as PROFILE_WEIGHTS, l as PitchSpelling, m as ProfileWeights, R as ReasonFlag, n as ResolvedKey, S as SafetyPartner, o as SafetyProfile, p as SafetyQuery, q as SafetyResult, r as SpelledKeyLike, s as SpelledKeyScale, V as VoiceSnapshot, t as chordFromDegree, u as chordFromSpan, v as chordFromSpec, w as chordPitchClasses, x as chordQualities, y as chordSpecIntervals, z as chordSpecOf, B as chordSpecQuality, D as chordToneRole, F as diatonicSeventh, G as diatonicTriad, H as dominantKeyOf, I as enharmonicKeyOf, J as enumerateSafePitches, L as evaluateSafety, M as intervalAboveRoot, O as isChordMember, Q as keyRelationBetween, T as makeChord, U as parallelKeyOf, W as profileWeights, X as relatedKeysOf, Y as relativeKeyOf, Z as spanFromChord, _ as spelledKeyOf, $ as subdominantKeyOf, a0 as toChordData, a1 as toKeyScale, a2 as transposeChord } from './coerce-Cr9AZsTY.js';
7
+ export { FiguredBassRealization, FiguredBassSuspension, HiddenParallelReading, ScaleLadderPosition, SpellingContext, classifySpelledInterval, createsBattuta, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, figuredBassOf, figuredBassRealization, isAugmentedMelodicInterval, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, minorKey, nearestScaleTone, nextVoicing, noteNames, pitchToScaleDegree, realizeFiguredBass, resolveKey, scaleByName, scaleLadderPitch, scaleLadderPosition, scaleOf, scaleTonesInDegreeOrder, shiftByScaleDegrees, spellChord, spellChordFromRoot, spellPitch, spellPitchClass, spellPitchClasses, spellScale, tryResolveKeyName, voiceLeadingCost } from './theory/index.js';
8
+ export { A as ALTERED_MASK, B as BLUES_MASK, C as CHROMATIC_MASK, D as DORIAN_MASK, a as DOUBLE_HARMONIC_MASK, H as HARMONIC_MINOR_MASK, L as LOCRIAN_MASK, b as LOCRIAN_NATURAL2_MASK, c as LYDIAN_DOMINANT_MASK, d as LYDIAN_MASK, M as MAJOR_MASK, e as MAJOR_PENTATONIC_MASK, f as MARWA_MASK, g as MELODIC_MINOR_MASK, h as MINOR_PENTATONIC_MASK, i as MIXOLYDIAN_B13_MASK, j as MIXOLYDIAN_MASK, k as MIYAKO_BUSHI_MASK, N as NAMED_SCALES, l as NATURAL_MINOR_MASK, O as OCTATONIC_HALF_WHOLE_MASK, m as OCTATONIC_WHOLE_HALF_MASK, P as PHRYGIAN_DOMINANT_MASK, n as PHRYGIAN_MASK, o as PURVI_MASK, R as RITSU_MASK, p as RYUKYU_MASK, S as SCALE_ALIASES, q as ScaleAliasName, r as ScaleName, s as ScaleNameInput, T as TODI_MASK, W as WHOLE_TONE_MASK, t as WORLD_SCALES, u as WorldScaleName, v as assertKeyVariant, w as assertModeMask, x as maskFromOffsets, y as namedScaleMask, z as requireScaleMask, E as resolveScaleName, F as variantOfMask } from './masks-BDxvQO8b.js';
9
+ export { A as AvailableTensionsOptions, a as AvoidNoteUse, b as AvoidNotesOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, d as ChordSymbolOptions, K as KeyMode, P as PartWritingOptions, e as PartWritingViolation, f as PartWritingViolationKind, S as SATB_RANGES, g as SCALE_SYSTEMS, h as ScaleChoice, i as ScaleSystem, j as Species, k as SpeciesOptions, l as SpelledVoicing, m as StyledVoicingOptions, T as TRANSPOSING_INSTRUMENTS, n as TransposingInstrument, o as TransposingInstrumentName, V as VoiceIndependenceOptions, p as VoiceIndependenceReport, q as VoiceRange, r as VoicingOptions, s as VoicingStyle, t as availableTensions, u as avoidNotes, v as checkPartWriting, w as checkSpecies, x as chordScaleReport, y as chordScales, z as formatChordSymbol, B as instrumentTransposition, D as isSignatureKey, E as keyFromFifths, F as keySignatureFifths, G as parseChordSymbol, H as scaleMatchesChord, I as scaleSystemOf, J as scalesForChanges, L as spellVoicing, M as supportsFunctionalHarmony, N as toSoundingPitch, O as toWrittenPitch, Q as transposeChordSymbol, R as tryParseChordSymbol, U as voiceChord, W as voiceChordStyled, X as voiceIndependence, Y as voiceProgression } from './index-COyI6W_w.js';
10
+ export { A as AnalyzeChordOptions, a as AnalyzedNote, B as BarPositionProfile, b as BorrowedSource, C as CADENCE_TYPES, c as CadenceHit, d as CadenceResult, e as CadenceType, f as ChordAnalysis, g as ChordSegmentation, h as ChordTimeline, i as ChordTimelineOptions, j as ChordTimelineResult, k as ChordToRomanOptions, l as ContourDirection, D as DetectCadenceOptions, E as ExplainRomanOptions, m as ExtractMotifsOptions, F as FormSection, n as FormSectionOptions, H as HARMONIC_FUNCTIONS, o as HarmonicFunction, I as IdentifiedVoiceNote, K as KeyContext, p as KeyProfileName, q as KeyProfilePair, r as KeyRegion, s as KeyTimelineOptions, M as MELODIC_CONTOUR_SHAPES, t as MOTIF_RELATION_KINDS, u as MelodicContour, v as MelodicContourShape, w as MelodicPhrase, x as MotifData, y as MotifGraph, z as MotifGraphEdge, G as MotifGraphNode, J as MotifGraphOptions, L as MotifOccurrence, N as MotifRelation, O as MotifRelationKind, P as MotifRelationSummary, Q as PivotChord, R as REDUCTION_LEVELS, S as REFERENCE_PROFILE_VERSION, T as RHYTHM_IOI_BINS, U as ReduceProgressionOptions, V as ReducedChord, W as ReductionBasis, X as ReductionLevel, Y as ReferenceCadence, Z as ReferenceChord, _ as ReferenceForm, $ as ReferenceHarmony, a0 as ReferenceKeyRegion, a1 as ReferenceMelody, a2 as ReferenceMotif, a3 as ReferencePhrase, a4 as ReferencePhraseMelody, a5 as ReferenceProfile, a6 as RejectedCandidate, a7 as RhythmAnalysis, a8 as RhythmAnalysisOptions, a9 as RomanExplanation, aa as SuspensionFigure, ab as TheoryLabel, ac as VoiceNote, ad as analyzeChord, ae as analyzeRhythm, af as analyzeVoice, ag as assertChordTimeline, ah as borrowedSource, ai as chordTimelineFromChords, aj as chordTimelineFromNotes, ak as chordToRoman, al as detectCadence, am as detectCadences, an as detectModulations, ao as explainRoman, ap as extractMotifs, aq as functionOf, ar as isBorrowedChord, as as isDiatonic, at as isMinorKey, au as keyTimelineFromNotes, av as melodicContour, aw as motifFromNotes, ax as motifGraph, ay as pivotChords, az as prevailingKeyOf, aA as reduceProgression, aB as relateMotifs, aC as romanToChord, aD as secondaryDominant, aE as secondaryDominantOf, aF as sectionsFromNotes, aG as toVoiceNotes } from './types-DPPzRpc3.js';
11
+ export { A as ArrangementAnalysis, a as ArrangementOptions, b as ArrangementSession, c as ArrangementTrack, d as AugmentedSixthKind, C as ChordMatch, e as Conflict, f as ConflictPartner, D as DetectChordOptions, g as DetectKeyOptions, H as Hypermeter, h as HypermeterOptions, K as KeyMatch, M as MODAL_SCALE_NAMES, i as ModalCandidate, j as ModalScaleName, P as Phrase, k as PhraseOptions, l as PhraseSignal, R as ReferenceProfileOptions, S as StructuralCadence, T as TensionPoint, m as TrackAnalysis, n as TrackEdit, o as TrackRole, p as analyzeArrangement, q as analyzePolyphony, r as analyzeReference, s as augmentedSixthChord, t as augmentedSixthFromPitchClasses, u as augmentedSixthKind, v as createArrangementSession, w as detectChord, x as detectChordBest, y as detectKey, z as detectKeyBest, B as detectKeyFromNotes, E as hypermeter, F as phrasesFromTimeline, G as spellAugmentedSixth, I as structuralCadences, J as tensionCurve, L as tensionCurveFrom } from './profile-kmJqJ3aO.js';
12
+ export { MelodicComparison, ReferenceComparison, ReferenceComparisonOptions, SpellLineOptions, assertReferenceProfile, compareMelodies, compareReferences, melodicSimilarity, spellLine } from './analyze/index.js';
13
+ export { C as ConsonanceClass, c as classifyInterval, i as isConsonantInterval, a as isPerfectInterval } from './index-DInQqT8Q.js';
14
+ export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from './index-CBQLVwv_.js';
15
+ export { B as BAR_STEPS, a as BASS_STYLES, b as BEAT_STEPS, c as BORROWED_DEGREES, d as BassLineOptions, e as BassSegment, f as BassStyle, g as BorrowedChord, C as COMPOSITION_PLAN_VERSION, h as Complexity, i as CompositionEvaluation, j as CompositionPlan, k as CompositionPlanOptions, l as CompositionViolation, m as CounterMelodyOptions, D as DRUM_NOTES, n as DeformOptions, o as Draw, p as DrumHit, q as DrumRole, r as DrumStyle, s as DrumVoice, t as DrumsOptions, E as EuclideanKick, u as EvaluateCompositionOptions, G as GENRES, v as GenerationContext, w as GenerationContextInput, x as Genre, y as GridEvent, z as GrooveFeel, A as GrooveSlot, F as GrooveStyle, H as GrooveTemplate, I as HarmonizeOptions, J as HarmonizePlacement, K as HarmonizeResult, L as HumanizeOptions, M as MelodyNote, N as MelodyOptions, O as MotifCell, P as MotifContour, Q as MotifNote, R as MotifOptions, S as MotifTransform, T as ORNAMENT_STYLES, U as OrnamentOptions, V as OrnamentStyle, W as PROVENANCE_BASES, X as PlannedChord, Y as PlannedMotif, Z as PlannedPhrase, _ as PlannedRhythm, $ as PlannedSection, a0 as PreserveWeights, a1 as ProgFunction, a2 as ProgStyle, a3 as ProgressionDegree, a4 as ProgressionOptions, a5 as ProgressionPreset, a6 as Provenance, a7 as ProvenanceBasis, a8 as ResolvedContext, a9 as RhythmEvent, aa as RhythmOptions, ab as STEP_BEATS, ac as Section, ad as SubstituteOptions, ae as Substitution, af as SubstitutionType, ag as SyncopateOptions, ah as Vocabulary, ai as VocabularyQuery, aj as applyGrooveTemplate, ak as assertVocabulary, al as deform, am as deriveCompositionPlan, an as developMotif, ao as double, ap as doubleTime, aq as drumVoiceOf, ar as evaluateComposition, as as extractGrooveTemplate, at as fitsQuery, au as generateBassLine, av as generateCounterMelody, aw as generateDrums, ax as generateMelody, ay as generateMotif, az as generateProgression, aA as generateRhythm, aB as gridMetricWeight, aC as halfTime, aD as humanize, aE as mergeVocabulary, aF as modalInterchangePalette, aG as motifToNoteEvents, aH as negativeHarmonyMirror, aI as onsetWeightCurve, aJ as ornament, aK as ornamentBy, aL as pickProgressionPreset, aM as pickVocabulary, aN as progressions, aO as progressionsByStyle, aP as resolveContext, aQ as rhythmDensity, aR as rhythmToNoteEvents, aS as selectVocabulary, aT as substituteChord, aU as syncopate, aV as thin, aW as transformMotif, aX as vocabularyOfKind, aY as withinCeiling } from './index-C1dnzRkt.js';
16
+ export { BASS_LICKS, BassLick, ClassifiedMelodyTone, DRUM_KIT, DRUM_PATTERNS, DrumPattern, DrumPatternOptions, DrumStroke, DrumVocabulary, FILL_ARCHETYPES, FILL_TYPES, FillArchetype, FillStroke, FillType, FillVelocity, ImitationAnswer, ImitationOptions, KICK_FIGURES, KICK_STEPS, KickFigure, KickPattern, KickSlot, LickMaterial, LickNote, MAX_DIFFICULTY, MIN_DIFFICULTY, MelodyToneRole, PlaceLicksOptions, assertCompositionPlan, classifyMelodyTones, harmonizeMelody, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, planTimeline, sustainsShift, sustainsStrokes } from './generate/index.js';
17
+ export { Arrangement, ArrangementData, ArrangementSettings, ArrangementSetup, ArrangementTensionOptions, BassLineSettings, Chord, Composer, ComposerOptions, CounterMelodySettings, DetectedKeyMatch, Duration, HarmonizedMelody, Instrument, Interval, Key, KeyData, Meter, Motif, MotifGenerateOptions, Note, Progression, ProgressionData, Rhythm, RhythmData, RhythmDeformOptions, Score, ScoreData, ScoreOptions, Tempo, TempoData, Timeline, TimelineData, TimelineRoman, Tuning, Voicing, VoicingData, VoicingIndependenceOptions, VoicingSafetyQuery } from './model/index.js';