@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,663 @@
1
+ /// <reference lib="esnext.disposable" />
2
+ import { h as NoteEvent } from './index-C9MYbuKS.js';
3
+ import { e as StringFingering, c as Limb, b as InstrumentProfileLike } from './positional-DLnfUgqG.js';
4
+
5
+ /**
6
+ * What makes a passage hard or impossible on an instrument.
7
+ *
8
+ * `noteOutOfRange` and `articulationUnavailable` belong to the first layer: the
9
+ * instrument has no position for what was written. `stringConflict`,
10
+ * `stretchTooWide`, `limbConflict` and `polyphonyExceeded` belong to the second:
11
+ * the notes exist but the arrangement cannot be held or struck. `tooFast`
12
+ * belongs to the third, the only one that depends on tempo.
13
+ *
14
+ * @category Core
15
+ */
16
+ type PlayabilityIssueType = 'noteOutOfRange' | 'articulationUnavailable' | 'stringConflict' | 'stretchTooWide' | 'limbConflict' | 'polyphonyExceeded' | 'tooFast';
17
+ /**
18
+ * Which playability layer an issue belongs to: 1 the note does not exist, 2 the
19
+ * arrangement does not hold together, 3 there is not enough time.
20
+ *
21
+ * @category Core
22
+ */
23
+ type PlayabilityLayer = 1 | 2 | 3;
24
+ /**
25
+ * One thing standing between a passage and a performance of it.
26
+ *
27
+ * @category Core
28
+ */
29
+ type PlayabilityIssue = {
30
+ type: PlayabilityIssueType;
31
+ layer: PlayabilityLayer;
32
+ /** Indices into the analysed note array, ascending. */
33
+ notes: readonly number[];
34
+ /** Where the problem occurs, in quarter-note beats. */
35
+ startBeat: number;
36
+ /**
37
+ * True when practice cannot fix it. Layers 1 and 2 depend on the instrument
38
+ * alone, so they are impossible however skilled the player; only a layer-3
39
+ * issue is a matter of degree.
40
+ */
41
+ impossible: boolean;
42
+ message: string;
43
+ };
44
+ /**
45
+ * How one note is actually produced: the string and fret it is stopped at, or
46
+ * the limb that strikes it.
47
+ *
48
+ * This is reported for every note that has a position at all, whether or not
49
+ * the passage raises issues, so a caller can apply its own standard rather than
50
+ * take this module's.
51
+ *
52
+ * @category Core
53
+ */
54
+ type NotePlacement = {
55
+ /** Index into the analysed note array. */
56
+ note: number;
57
+ /** String instruments: where the note is stopped. */
58
+ fingering?: StringFingering;
59
+ /** Percussion: which limb plays the stroke. */
60
+ limb?: Limb;
61
+ };
62
+ /**
63
+ * The verdict on a passage: how hard it is, what stands in the way, and how
64
+ * each note would be produced.
65
+ *
66
+ * @category Core
67
+ */
68
+ type PlayabilityReport = {
69
+ /**
70
+ * Movement per unit time, mapped onto 1 (trivial) to 5 (at the limit).
71
+ * Without a tempo the passage is measured at 120 BPM, so the number stays
72
+ * comparable between passages; with one it rises as the tempo does.
73
+ */
74
+ difficulty: number;
75
+ issues: PlayabilityIssue[];
76
+ placements: NotePlacement[];
77
+ };
78
+ /**
79
+ * Judge whether a passage can be played on an instrument, and how hard it is.
80
+ *
81
+ * Inspection is deliberately separate from generation: this answers "can this
82
+ * be played" for a chart handed to a player or a practice tool, and never
83
+ * rewrites or rejects anything. The three layers are reported together but stay
84
+ * distinct — an out-of-range note or an impossible stretch is not the bottom of
85
+ * the difficulty scale but a different axis, since no amount of skill puts a
86
+ * note on an instrument that does not have it. Only the third layer consults
87
+ * `bpm`, so omitting the tempo reports what the instrument alone decides.
88
+ *
89
+ * @param notes The passage, in any order. Drum hits qualify as note events.
90
+ * @param profile The instrument to play it on.
91
+ * @param bpm Tempo in quarter-note beats per minute; enables the third layer.
92
+ * @returns Difficulty, the issues found, and each note's string/fret or limb.
93
+ * @throws If the notes are not note events, the tempo is not a finite positive
94
+ * number of beats per minute, or the profile describes no instrument — a neck
95
+ * with no strings or a kit no limb reaches, whatever the passage holds.
96
+ *
97
+ * @example
98
+ * ```ts
99
+ * import { BASS_4_STRING, playability } from '@libraz/libcantus';
100
+ * const report = playability([{ pitch: 27, startBeat: 0, durationBeat: 1 }], BASS_4_STRING);
101
+ * report.issues[0]?.type; // 'noteOutOfRange'
102
+ * ```
103
+ * @category Core
104
+ */
105
+ declare function playability(notes: readonly NoteEvent[], profile: InstrumentProfileLike, bpm?: number): PlayabilityReport;
106
+
107
+ /**
108
+ * Note values: the written durations a score shows — a base value, its
109
+ * augmentation dots, and an optional tuplet ratio — and the conversion between
110
+ * them and the quarter-note beats the rest of the library measures in.
111
+ *
112
+ * The base values are named the American way (whole, half, quarter, eighth),
113
+ * matching the library's "quarter-note beat" convention and the vocabulary of
114
+ * the MIDI and DAW world this engine reads events from.
115
+ */
116
+ /**
117
+ * A written base note value, from the whole note down to the sixty-fourth.
118
+ *
119
+ * Longer values (the breve and beyond) are written as tied notes; see
120
+ * {@link beatsToTiedDurations}.
121
+ *
122
+ * @category Rhythm & Meter
123
+ */
124
+ type NoteValue = 'whole' | 'half' | 'quarter' | 'eighth' | 'sixteenth' | 'thirtySecond' | 'sixtyFourth';
125
+ /**
126
+ * Every base note value, longest first.
127
+ *
128
+ * @category Rhythm & Meter
129
+ */
130
+ declare const NOTE_VALUES: readonly NoteValue[];
131
+ /**
132
+ * A tuplet ratio: `actual` written notes played in the time of `normal` ones —
133
+ * `{ actual: 3, normal: 2 }` for a triplet, `{ actual: 5, normal: 4 }` for a
134
+ * quintuplet.
135
+ *
136
+ * @category Rhythm & Meter
137
+ */
138
+ type Tuplet = {
139
+ /** How many notes are written. */
140
+ actual: number;
141
+ /** How many of the same base value they occupy. */
142
+ normal: number;
143
+ };
144
+ /**
145
+ * A written duration: a base value, optional augmentation dots, and an optional
146
+ * tuplet ratio. Its length is `base * (2 - 2^-dots) * normal / actual`.
147
+ *
148
+ * @category Rhythm & Meter
149
+ */
150
+ type DurationData = {
151
+ base: NoteValue;
152
+ /** Augmentation dots, 0 when absent; up to four are accepted. */
153
+ dots?: number;
154
+ tuplet?: Tuplet;
155
+ };
156
+ /**
157
+ * A duration as {@link beatsToDuration} spells it, with the dot count always
158
+ * stated.
159
+ *
160
+ * @category Rhythm & Meter
161
+ */
162
+ type SpelledDuration = {
163
+ base: NoteValue;
164
+ dots: number;
165
+ tuplet?: Tuplet;
166
+ };
167
+ /**
168
+ * Length of a written duration in beats.
169
+ *
170
+ * @param duration The duration, or a bare base value as shorthand for an
171
+ * undotted one.
172
+ * @param options `beatUnit` sets what one beat is; a quarter note by default,
173
+ * so a dotted quarter reads as 1.5. Pass `{ base: 'quarter', dots: 1 }` to
174
+ * count in the felt beats of a compound meter.
175
+ * @returns The length in beats.
176
+ * @throws If the base value is unknown, the dot count is not an integer in
177
+ * 0..4, or a tuplet side is not a positive integer.
178
+ * @example
179
+ * ```ts
180
+ * import { durationToBeats } from '@libraz/libcantus';
181
+ * durationToBeats('quarter'); // 1
182
+ * durationToBeats({ base: 'quarter', dots: 1 }); // 1.5
183
+ * durationToBeats({ base: 'eighth', tuplet: { actual: 3, normal: 2 } }) * 3; // 1 — three
184
+ * // eighth-note triplets fill the beat two eighths would
185
+ * ```
186
+ * @category Rhythm & Meter
187
+ */
188
+ declare function durationToBeats(duration: NoteValue | DurationData, options?: {
189
+ beatUnit?: NoteValue | DurationData;
190
+ }): number;
191
+ /**
192
+ * Spell a length in beats as the note value a score would show.
193
+ *
194
+ * The spelling is the conventional one, not merely an arithmetically valid one:
195
+ * 1.5 beats is a dotted quarter rather than a quarter tied to an eighth, and a
196
+ * third of a beat is an eighth triplet rather than a twenty-fourth note. Plain
197
+ * values are preferred to dotted ones and both to tuplets, and within the
198
+ * tuplets triplets come before quintuplets and septuplets.
199
+ *
200
+ * Lengths are matched within 1e-6 quarter notes, so a rounded decimal such as
201
+ * 0.3333333 still reads as a triplet. The tolerance is measured in quarter
202
+ * notes whatever `beatUnit` names, so a longer beat unit narrows it in
203
+ * proportion: under `{ beatUnit: 'whole' }` it is 2.5e-7 of a beat.
204
+ *
205
+ * @param beats The length in beats.
206
+ * @param options `beatUnit` sets what one beat is; a quarter note by default.
207
+ * @returns The base value, its dot count, and its tuplet when it has one.
208
+ * @throws If `beats` is not positive, or — as a `NoSolutionError` — if no single
209
+ * note value spells it, as for 5 beats in 4/4. Use
210
+ * {@link beatsToTiedDurations} for those.
211
+ * @example
212
+ * ```ts
213
+ * import { beatsToDuration } from '@libraz/libcantus';
214
+ * beatsToDuration(1.5); // { base: 'quarter', dots: 1 }
215
+ * beatsToDuration(1 / 3); // { base: 'eighth', dots: 0, tuplet: { actual: 3, normal: 2 } }
216
+ * ```
217
+ * @category Rhythm & Meter
218
+ */
219
+ declare function beatsToDuration(beats: number, options?: {
220
+ beatUnit?: NoteValue | DurationData;
221
+ }): SpelledDuration;
222
+ /**
223
+ * Spell a length in beats as a chain of tied note values.
224
+ *
225
+ * A length with a single spelling comes back as a one-element chain. Anything
226
+ * else is broken into undotted values, longest first, and a value immediately
227
+ * followed by its own half is then written as a dot instead: 5 beats reads as a
228
+ * whole note tied to a quarter, and 1.9375 beats as a double-dotted quarter tied
229
+ * to a dotted thirty-second. The dot is only written where it leaves the chain
230
+ * in longest-first order, so 10 beats reads as two whole notes tied to a half
231
+ * rather than as a whole note tied to a longer dotted whole. The chain knows
232
+ * nothing of barlines or beat grouping — an engraver splits further at those —
233
+ * and it uses no tuplets, so a length off the plain grid and with no single
234
+ * spelling has no chain either.
235
+ *
236
+ * @param beats The length in beats.
237
+ * @param options `beatUnit` sets what one beat is; a quarter note by default.
238
+ * @returns The tied durations, longest first, summing to `beats`.
239
+ * @throws If `beats` is not positive, if the chain would exceed the generation
240
+ * budget, or — as a `NoSolutionError` — if no chain of plain and dotted values
241
+ * sums to it.
242
+ * @example
243
+ * ```ts
244
+ * import { beatsToTiedDurations } from '@libraz/libcantus';
245
+ * beatsToTiedDurations(5); // [{ base: 'whole', dots: 0 }, { base: 'quarter', dots: 0 }]
246
+ * ```
247
+ * @category Rhythm & Meter
248
+ */
249
+ declare function beatsToTiedDurations(beats: number, options?: {
250
+ beatUnit?: NoteValue | DurationData;
251
+ }): SpelledDuration[];
252
+
253
+ /**
254
+ * A validated note retaining its position in the caller's original array.
255
+ *
256
+ * @category Core
257
+ */
258
+ type IndexedNoteEvent = {
259
+ readonly note: Readonly<NoteEvent>;
260
+ readonly originalIndex: number;
261
+ readonly endBeat: number;
262
+ };
263
+ /**
264
+ * Which note wins when several sound from the same onset.
265
+ *
266
+ * `'highest'` and `'lowest'` name a voice, so the answer does not depend on the
267
+ * order the caller happened to store the chord in; `'last'` takes the one
268
+ * latest in the input array. Two notes of the same pitch name no voice apart,
269
+ * so both voice tie-breaks settle a unison on the lower `originalIndex` and
270
+ * name the same note.
271
+ *
272
+ * @category Core
273
+ */
274
+ type OnsetTieBreak = 'highest' | 'lowest' | 'last';
275
+ /**
276
+ * Binary-searchable, stable-sorted index over note onsets and active spans.
277
+ *
278
+ * @category Core
279
+ */
280
+ type NoteEventIndex = {
281
+ /** Release the handle now; later calls on it fail with `RELEASED_HANDLE`. */
282
+ [Symbol.dispose](): void;
283
+ notes: readonly IndexedNoteEvent[];
284
+ /**
285
+ * Latest-onset note sounding at `beat`. Simultaneous onsets are resolved by
286
+ * the index's {@link OnsetTieBreak}.
287
+ *
288
+ * @throws If `beat` is not finite.
289
+ */
290
+ at: (beat: number) => IndexedNoteEvent | undefined;
291
+ /**
292
+ * Whether one or more sounding notes attack at `beat`.
293
+ *
294
+ * @throws If `beat` is not finite.
295
+ */
296
+ attacksAt: (beat: number) => boolean;
297
+ /**
298
+ * Unique sounding-note attack beats strictly inside `(startBeat, endBeat)`.
299
+ *
300
+ * @throws If either bound is not finite.
301
+ */
302
+ onsetsBetween: (startBeat: number, endBeat: number) => number[];
303
+ };
304
+ /**
305
+ * How an index reads the events it is built from.
306
+ *
307
+ * @category Core
308
+ */
309
+ type NoteEventIndexOptions = {
310
+ allowNonPositiveDuration?: boolean;
311
+ tieBreak?: OnsetTieBreak;
312
+ budget?: number;
313
+ /** What the events are, for the validation error message. */
314
+ name?: string;
315
+ };
316
+ /**
317
+ * Validate and stable-sort note events once, then expose onset and active-note
318
+ * lookups that cost `O(log n + k)`, where `k` is how many notes share the onset
319
+ * the answer comes from. Non-positive-duration notes may be retained for
320
+ * callers that intentionally filter them later, but never count as sounding.
321
+ *
322
+ * @category Core
323
+ */
324
+ declare function createNoteEventIndex(events: readonly NoteEvent[], options?: NoteEventIndexOptions): NoteEventIndex;
325
+
326
+ /**
327
+ * Tempo and time conversion: beats to wall-clock seconds across tempo changes,
328
+ * and beats to MIDI ticks.
329
+ *
330
+ * Positions are measured in quarter-note beats, matching the rest of the
331
+ * library's beat convention. A {@link TempoMap} is piecewise constant: each
332
+ * entry sets the tempo from its beat onwards, so the elapsed time over a span is
333
+ * the sum of the segments it crosses rather than the tempo at either end.
334
+ */
335
+ /**
336
+ * A tempo change: the beat it takes effect on, and the tempo it sets.
337
+ *
338
+ * The tempo holds until the next entry, so a map of one entry is a constant
339
+ * tempo for the whole timeline.
340
+ *
341
+ * @category Rhythm & Meter
342
+ */
343
+ type TempoEvent = {
344
+ /** Onset in quarter-note beats, absolute from the start of the timeline. */
345
+ readonly startBeat: number;
346
+ /** Quarter-note beats per minute from `startBeat` onwards. */
347
+ readonly bpm: number;
348
+ };
349
+ /**
350
+ * A tempo track: {@link TempoEvent}s sorted by `startBeat`, strictly ascending.
351
+ *
352
+ * The first entry is the time origin — {@link beatsToSeconds} returns 0 for its
353
+ * `startBeat` — and its tempo also governs the beats before it, which is where
354
+ * a pickup sounds. A map cannot say anything else about that stretch, and a
355
+ * piece is played into its first downbeat at the tempo it starts in, so elapsed
356
+ * time there is negative rather than an error.
357
+ *
358
+ * @category Rhythm & Meter
359
+ */
360
+ type TempoMap = readonly TempoEvent[];
361
+ /**
362
+ * Wall-clock seconds from the start of a tempo map to a beat.
363
+ *
364
+ * The result integrates every tempo segment the span crosses; it is not the
365
+ * tempo in effect at `beat` applied to the whole span.
366
+ *
367
+ * A beat before the map's first event reports negative elapsed time, at the
368
+ * opening tempo: a pickup sounds before the downbeat, and asking when it sounds
369
+ * is a fair question.
370
+ *
371
+ * @param beat Position in quarter-note beats.
372
+ * @param map The tempo map; its first event is the time origin.
373
+ * @returns Elapsed seconds, 0 at the map's first event and negative before it.
374
+ * @throws If the map is empty, unsorted, or carries a tempo outside 0.1..1000
375
+ * quarter-note beats per minute.
376
+ * @example
377
+ * ```ts
378
+ * import { beatsToSeconds } from '@libraz/libcantus';
379
+ * const map = [{ startBeat: 0, bpm: 120 }, { startBeat: 4, bpm: 60 }];
380
+ * beatsToSeconds(8, map); // 6 = 4 beats at 120 + 4 beats at 60
381
+ * ```
382
+ * @category Rhythm & Meter
383
+ */
384
+ declare function beatsToSeconds(beat: number, map: TempoMap): number;
385
+ /**
386
+ * The beat reached after a number of seconds — the inverse of
387
+ * {@link beatsToSeconds}.
388
+ *
389
+ * @param seconds Elapsed seconds from the map's first event; negative for a
390
+ * position before it, such as a pickup.
391
+ * @param map The tempo map.
392
+ * @returns The position in quarter-note beats.
393
+ * @throws If the map is malformed or `seconds` is not finite.
394
+ * @example
395
+ * ```ts
396
+ * import { secondsToBeats } from '@libraz/libcantus';
397
+ * const map = [{ startBeat: 0, bpm: 120 }, { startBeat: 4, bpm: 60 }];
398
+ * secondsToBeats(6, map); // 8
399
+ * ```
400
+ * @category Rhythm & Meter
401
+ */
402
+ declare function secondsToBeats(seconds: number, map: TempoMap): number;
403
+ /**
404
+ * Duration in seconds of a span of beats.
405
+ *
406
+ * Equal to the difference of two {@link beatsToSeconds} calls — the integral is
407
+ * additive, so that reading is exact — but integrated over the span directly, so
408
+ * a short note late in a long piece does not lose precision to the subtraction
409
+ * of two large elapsed times.
410
+ *
411
+ * @param startBeat Where the span begins, in quarter-note beats; a pickup
412
+ * starts before the map's first event and is measured like any other span.
413
+ * @param lengthBeats How long the span lasts, in quarter-note beats.
414
+ * @param map The tempo map.
415
+ * @returns The span's duration in seconds, never negative.
416
+ * @throws If the map is malformed or the length is negative.
417
+ * @example
418
+ * ```ts
419
+ * import { durationToSeconds } from '@libraz/libcantus';
420
+ * const map = [{ startBeat: 0, bpm: 120 }, { startBeat: 4, bpm: 60 }];
421
+ * durationToSeconds(2, 4, map); // 3 = 2 beats at 120 + 2 beats at 60
422
+ * ```
423
+ * @category Rhythm & Meter
424
+ */
425
+ declare function durationToSeconds(startBeat: number, lengthBeats: number, map: TempoMap): number;
426
+ /**
427
+ * The tempo in effect at a beat.
428
+ *
429
+ * A beat before the first event reads the opening tempo, which is the tempo a
430
+ * pickup is played at.
431
+ *
432
+ * @param beat Position in quarter-note beats.
433
+ * @param map The tempo map.
434
+ * @returns Quarter-note beats per minute.
435
+ * @throws If the map is malformed.
436
+ * @example
437
+ * ```ts
438
+ * import { tempoAt } from '@libraz/libcantus';
439
+ * tempoAt(5, [{ startBeat: 0, bpm: 120 }, { startBeat: 4, bpm: 60 }]); // 60
440
+ * ```
441
+ * @category Rhythm & Meter
442
+ */
443
+ declare function tempoAt(beat: number, map: TempoMap): number;
444
+ /**
445
+ * Convert quarter-note beats to MIDI ticks.
446
+ *
447
+ * Ticks are whole units of a sequencer's grid, so the result is rounded to the
448
+ * nearest tick; a beat that is not on the grid is not representable and comes
449
+ * back quantized.
450
+ *
451
+ * A position before the first downbeat is a negative tick count, which is how a
452
+ * pickup crosses the MIDI boundary and comes back. A position that rounds to
453
+ * the downbeat from below comes back as positive zero: `-0` and `0` are the
454
+ * same tick, and only one of them keys as it under `Object.is`.
455
+ *
456
+ * @param beat Position or length in quarter-note beats.
457
+ * @param ppq Pulses (ticks) per quarter note, e.g. 96, 480, or 960.
458
+ * @returns The whole tick count.
459
+ * @throws If `beat` is not finite, `ppq` is not a positive integer, or the
460
+ * tick count is past the safe integers.
461
+ * @example
462
+ * ```ts
463
+ * import { beatsToTicks } from '@libraz/libcantus';
464
+ * beatsToTicks(1.5, 480); // 720
465
+ * ```
466
+ * @category Rhythm & Meter
467
+ */
468
+ declare function beatsToTicks(beat: number, ppq: number): number;
469
+ /**
470
+ * Convert MIDI ticks to quarter-note beats.
471
+ *
472
+ * @param ticks Whole tick count, negative before the first downbeat.
473
+ * @param ppq Pulses (ticks) per quarter note, e.g. 96, 480, or 960.
474
+ * @returns The position or length in quarter-note beats.
475
+ * @throws If `ticks` is not an integer or `ppq` is not a positive integer.
476
+ * @example
477
+ * ```ts
478
+ * import { ticksToBeats } from '@libraz/libcantus';
479
+ * ticksToBeats(720, 480); // 1.5
480
+ * ```
481
+ * @category Rhythm & Meter
482
+ */
483
+ declare function ticksToBeats(ticks: number, ppq: number): number;
484
+
485
+ /**
486
+ * Tuning and microtonality: frequency conversion, cents, arbitrary equal
487
+ * temperaments (EDO), and just-intonation ratios.
488
+ *
489
+ * The rest of the library reasons in twelve-tone pitch classes, which is a
490
+ * deliberate scope choice for tonal theory. This module is the escape hatch for
491
+ * anyone who needs actual frequencies, cents, non-12 equal temperaments, or the
492
+ * acoustic (just) tuning behind the tempered intervals.
493
+ */
494
+ /**
495
+ * An equal-tempered tuning: a reference pitch and a number of equal divisions of
496
+ * the octave. With `divisions === 12` a step index is an ordinary MIDI number.
497
+ *
498
+ * @category Pitch & Intervals
499
+ */
500
+ type TuningTable = {
501
+ /** Step index (MIDI number when `divisions` is 12) whose frequency is `refFreq`. */
502
+ readonly refStep: number;
503
+ /** Frequency in Hz of `refStep`. */
504
+ readonly refFreq: number;
505
+ /** Equal divisions of the octave (12 standard; e.g. 19 or 31 for microtonal). */
506
+ readonly divisions: number;
507
+ };
508
+ /**
509
+ * Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz.
510
+ *
511
+ * @category Pitch & Intervals
512
+ */
513
+ declare const TWELVE_TET: TuningTable;
514
+ /**
515
+ * Build an equal temperament with `n` divisions of the octave.
516
+ *
517
+ * @param n Divisions of the octave (e.g. 19, 24, 31).
518
+ * @param refFreq Reference frequency in Hz (default 440).
519
+ * @param refStep Step index of the reference (default 69).
520
+ * @returns The tuning.
521
+ * @example
522
+ * ```ts
523
+ * import { edo, frequencyOf } from '@libraz/libcantus';
524
+ * const et19 = edo(19); // { refStep: 69, refFreq: 440, divisions: 19 }
525
+ * frequencyOf(70, et19); // one 19-EDO step above A4
526
+ * ```
527
+ * @category Pitch & Intervals
528
+ */
529
+ declare function edo(n: number, refFreq?: number, refStep?: number): TuningTable;
530
+ /**
531
+ * Frequency in Hz of a step index under a tuning.
532
+ *
533
+ * @param step Step index (a MIDI number under 12-EDO).
534
+ * @param tuning The tuning (default 12-TET).
535
+ * @returns The frequency in Hz.
536
+ * @example
537
+ * ```ts
538
+ * import { frequencyOf } from '@libraz/libcantus';
539
+ * frequencyOf(69); // 440 (A4 in 12-TET)
540
+ * frequencyOf(60); // middle C in Hz
541
+ * ```
542
+ * @category Pitch & Intervals
543
+ */
544
+ declare function frequencyOf(step: number, tuning?: TuningTable): number;
545
+ /**
546
+ * Nearest step index to a frequency under a tuning (the inverse of
547
+ * {@link frequencyOf}, rounded).
548
+ *
549
+ * @param freq Frequency in Hz.
550
+ * @param tuning The tuning (default 12-TET).
551
+ * @returns The nearest step index.
552
+ * @category Pitch & Intervals
553
+ */
554
+ declare function nearestStep(freq: number, tuning?: TuningTable): number;
555
+ /**
556
+ * Step index of a frequency under a tuning, unrounded.
557
+ *
558
+ * The exact inverse of {@link frequencyOf}. {@link nearestStep} rounds it,
559
+ * which discards how far off the pitch actually is — the figure a tuner
560
+ * display, a pitch-bend amount, or an intonation check is built on.
561
+ *
562
+ * @param freq Frequency in Hz.
563
+ * @param tuning The tuning (default 12-TET).
564
+ * @returns The fractional step index.
565
+ * @example
566
+ * ```ts
567
+ * import { stepOf } from '@libraz/libcantus';
568
+ * stepOf(442); // slightly above 69, the step for A440
569
+ * ```
570
+ * @category Pitch & Intervals
571
+ */
572
+ declare function stepOf(freq: number, tuning?: TuningTable): number;
573
+ /**
574
+ * How far a frequency sits from its nearest step, in cents.
575
+ *
576
+ * Positive means sharp of the step, negative flat.
577
+ *
578
+ * @param freq Frequency in Hz.
579
+ * @param tuning The tuning (default 12-TET).
580
+ * @returns The signed deviation in cents.
581
+ * @example
582
+ * ```ts
583
+ * import { centsFromNearestStep } from '@libraz/libcantus';
584
+ * Math.round(centsFromNearestStep(442)); // 8
585
+ * ```
586
+ * @category Pitch & Intervals
587
+ */
588
+ declare function centsFromNearestStep(freq: number, tuning?: TuningTable): number;
589
+ /**
590
+ * Steps spanned by an interval in cents, unrounded — the inverse of
591
+ * {@link centsOfSteps}.
592
+ *
593
+ * @param cents The interval in cents.
594
+ * @param tuning The tuning (default 12-TET).
595
+ * @returns The fractional step count.
596
+ * @category Pitch & Intervals
597
+ */
598
+ declare function stepsOfCents(cents: number, tuning?: TuningTable): number;
599
+ /**
600
+ * The frequency ratio an interval in cents spans — the inverse of
601
+ * {@link ratioToCents}.
602
+ *
603
+ * Multiply a frequency by this to move it by that many cents, which is how a
604
+ * cents offset (a pitch-bend spec, a tuning table entry) is applied.
605
+ *
606
+ * @param cents The interval in cents.
607
+ * @returns The frequency ratio.
608
+ * @example
609
+ * ```ts
610
+ * import { centsToRatio } from '@libraz/libcantus';
611
+ * 440 * centsToRatio(14); // A440 raised by 14 cents
612
+ * ```
613
+ * @category Pitch & Intervals
614
+ */
615
+ declare function centsToRatio(cents: number): number;
616
+ /**
617
+ * Interval in cents between two frequencies.
618
+ *
619
+ * @param a Lower/first frequency in Hz.
620
+ * @param b Upper/second frequency in Hz.
621
+ * @returns Cents from `a` to `b` (negative if `b` is lower).
622
+ * @category Pitch & Intervals
623
+ */
624
+ declare function centsBetweenFreq(a: number, b: number): number;
625
+ /**
626
+ * Cents spanned by a number of equal-temperament steps.
627
+ *
628
+ * @param steps Number of steps.
629
+ * @param tuning The tuning (default 12-TET).
630
+ * @returns The cents.
631
+ * @category Pitch & Intervals
632
+ */
633
+ declare function centsOfSteps(steps: number, tuning?: TuningTable): number;
634
+ /**
635
+ * Cents of a frequency ratio, e.g. `ratioToCents(3, 2)` ≈ 701.955 for the just
636
+ * perfect fifth.
637
+ *
638
+ * @param numerator Ratio numerator.
639
+ * @param denominator Ratio denominator.
640
+ * @returns The interval in cents.
641
+ * @category Pitch & Intervals
642
+ */
643
+ declare function ratioToCents(numerator: number, denominator: number): number;
644
+ /**
645
+ * Five-limit just-intonation ratios for the twelve interval classes above a
646
+ * unison, indexed by semitone class (0..12).
647
+ *
648
+ * @category Pitch & Intervals
649
+ */
650
+ declare const JUST_RATIOS: Readonly<Record<0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12, readonly [number, number]>>;
651
+ /**
652
+ * Cents by which a five-limit just interval departs from its 12-TET tempering
653
+ * (positive means the just interval is wider).
654
+ *
655
+ * @param semitoneClass Semitone class in [0, 12].
656
+ * @returns The deviation in cents.
657
+ * @throws If `semitoneClass` is not an integer in [0, 12].
658
+ * @category Pitch & Intervals
659
+ */
660
+ declare function justDeviationCents(semitoneClass: number): number;
661
+
662
+ export { playability as A, ratioToCents as B, secondsToBeats as C, stepOf as E, stepsOfCents as F, tempoAt as G, ticksToBeats as H, JUST_RATIOS as J, NOTE_VALUES as N, TWELVE_TET as T, beatsToDuration as l, beatsToSeconds as m, beatsToTicks as n, beatsToTiedDurations as o, centsBetweenFreq as p, centsFromNearestStep as q, centsOfSteps as r, centsToRatio as s, createNoteEventIndex as t, durationToBeats as u, durationToSeconds as v, edo as w, frequencyOf as x, justDeviationCents as y, nearestStep as z };
663
+ export type { DurationData as D, IndexedNoteEvent as I, OnsetTieBreak as O, PlayabilityIssue as P, SpelledDuration as S, NoteEventIndex as a, NoteEventIndexOptions as b, NotePlacement as c, NoteValue as d, PlayabilityIssueType as e, PlayabilityLayer as f, PlayabilityReport as g, TempoEvent as h, TempoMap as i, TuningTable as j, Tuplet as k };