@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,665 @@
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
+ /** The tie-breaks an index accepts, in the order an error lists them. */
264
+ declare const ONSET_TIE_BREAKS: readonly ["highest", "lowest", "last"];
265
+ /**
266
+ * Which note wins when several sound from the same onset.
267
+ *
268
+ * `'highest'` and `'lowest'` name a voice, so the answer does not depend on the
269
+ * order the caller happened to store the chord in; `'last'` takes the one
270
+ * latest in the input array. Two notes of the same pitch name no voice apart,
271
+ * so both voice tie-breaks settle a unison on the lower `originalIndex` and
272
+ * name the same note.
273
+ *
274
+ * @category Core
275
+ */
276
+ type OnsetTieBreak = (typeof ONSET_TIE_BREAKS)[number];
277
+ /**
278
+ * Binary-searchable, stable-sorted index over note onsets and active spans.
279
+ *
280
+ * @category Core
281
+ */
282
+ type NoteEventIndex = {
283
+ /** Release the handle now; later calls on it fail with `RELEASED_HANDLE`. */
284
+ [Symbol.dispose](): void;
285
+ notes: readonly IndexedNoteEvent[];
286
+ /**
287
+ * Latest-onset note sounding at `beat`. Simultaneous onsets are resolved by
288
+ * the index's {@link OnsetTieBreak}.
289
+ *
290
+ * @throws If `beat` is not finite.
291
+ */
292
+ at: (beat: number) => IndexedNoteEvent | undefined;
293
+ /**
294
+ * Whether one or more sounding notes attack at `beat`.
295
+ *
296
+ * @throws If `beat` is not finite.
297
+ */
298
+ attacksAt: (beat: number) => boolean;
299
+ /**
300
+ * Unique sounding-note attack beats strictly inside `(startBeat, endBeat)`.
301
+ *
302
+ * @throws If either bound is not finite.
303
+ */
304
+ onsetsBetween: (startBeat: number, endBeat: number) => number[];
305
+ };
306
+ /**
307
+ * How an index reads the events it is built from.
308
+ *
309
+ * @category Core
310
+ */
311
+ type NoteEventIndexOptions = {
312
+ allowNonPositiveDuration?: boolean;
313
+ tieBreak?: OnsetTieBreak;
314
+ budget?: number;
315
+ /** What the events are, for the validation error message. */
316
+ name?: string;
317
+ };
318
+ /**
319
+ * Validate and stable-sort note events once, then expose onset and active-note
320
+ * lookups that cost `O(log n + k)`, where `k` is how many notes share the onset
321
+ * the answer comes from. Non-positive-duration notes may be retained for
322
+ * callers that intentionally filter them later, but never count as sounding.
323
+ *
324
+ * @category Core
325
+ */
326
+ declare function createNoteEventIndex(events: readonly NoteEvent[], options?: NoteEventIndexOptions): NoteEventIndex;
327
+
328
+ /**
329
+ * Tempo and time conversion: beats to wall-clock seconds across tempo changes,
330
+ * and beats to MIDI ticks.
331
+ *
332
+ * Positions are measured in quarter-note beats, matching the rest of the
333
+ * library's beat convention. A {@link TempoMap} is piecewise constant: each
334
+ * entry sets the tempo from its beat onwards, so the elapsed time over a span is
335
+ * the sum of the segments it crosses rather than the tempo at either end.
336
+ */
337
+ /**
338
+ * A tempo change: the beat it takes effect on, and the tempo it sets.
339
+ *
340
+ * The tempo holds until the next entry, so a map of one entry is a constant
341
+ * tempo for the whole timeline.
342
+ *
343
+ * @category Rhythm & Meter
344
+ */
345
+ type TempoEvent = {
346
+ /** Onset in quarter-note beats, absolute from the start of the timeline. */
347
+ readonly startBeat: number;
348
+ /** Quarter-note beats per minute from `startBeat` onwards. */
349
+ readonly bpm: number;
350
+ };
351
+ /**
352
+ * A tempo track: {@link TempoEvent}s sorted by `startBeat`, strictly ascending.
353
+ *
354
+ * The first entry is the time origin — {@link beatsToSeconds} returns 0 for its
355
+ * `startBeat` — and its tempo also governs the beats before it, which is where
356
+ * a pickup sounds. A map cannot say anything else about that stretch, and a
357
+ * piece is played into its first downbeat at the tempo it starts in, so elapsed
358
+ * time there is negative rather than an error.
359
+ *
360
+ * @category Rhythm & Meter
361
+ */
362
+ type TempoMap = readonly TempoEvent[];
363
+ /**
364
+ * Wall-clock seconds from the start of a tempo map to a beat.
365
+ *
366
+ * The result integrates every tempo segment the span crosses; it is not the
367
+ * tempo in effect at `beat` applied to the whole span.
368
+ *
369
+ * A beat before the map's first event reports negative elapsed time, at the
370
+ * opening tempo: a pickup sounds before the downbeat, and asking when it sounds
371
+ * is a fair question.
372
+ *
373
+ * @param beat Position in quarter-note beats.
374
+ * @param map The tempo map; its first event is the time origin.
375
+ * @returns Elapsed seconds, 0 at the map's first event and negative before it.
376
+ * @throws If the map is empty, unsorted, or carries a tempo outside 0.1..1000
377
+ * quarter-note beats per minute.
378
+ * @example
379
+ * ```ts
380
+ * import { beatsToSeconds } from '@libraz/libcantus';
381
+ * const map = [{ startBeat: 0, bpm: 120 }, { startBeat: 4, bpm: 60 }];
382
+ * beatsToSeconds(8, map); // 6 = 4 beats at 120 + 4 beats at 60
383
+ * ```
384
+ * @category Rhythm & Meter
385
+ */
386
+ declare function beatsToSeconds(beat: number, map: TempoMap): number;
387
+ /**
388
+ * The beat reached after a number of seconds — the inverse of
389
+ * {@link beatsToSeconds}.
390
+ *
391
+ * @param seconds Elapsed seconds from the map's first event; negative for a
392
+ * position before it, such as a pickup.
393
+ * @param map The tempo map.
394
+ * @returns The position in quarter-note beats.
395
+ * @throws If the map is malformed or `seconds` is not finite.
396
+ * @example
397
+ * ```ts
398
+ * import { secondsToBeats } from '@libraz/libcantus';
399
+ * const map = [{ startBeat: 0, bpm: 120 }, { startBeat: 4, bpm: 60 }];
400
+ * secondsToBeats(6, map); // 8
401
+ * ```
402
+ * @category Rhythm & Meter
403
+ */
404
+ declare function secondsToBeats(seconds: number, map: TempoMap): number;
405
+ /**
406
+ * Duration in seconds of a span of beats.
407
+ *
408
+ * Equal to the difference of two {@link beatsToSeconds} calls — the integral is
409
+ * additive, so that reading is exact — but integrated over the span directly, so
410
+ * a short note late in a long piece does not lose precision to the subtraction
411
+ * of two large elapsed times.
412
+ *
413
+ * @param startBeat Where the span begins, in quarter-note beats; a pickup
414
+ * starts before the map's first event and is measured like any other span.
415
+ * @param lengthBeats How long the span lasts, in quarter-note beats.
416
+ * @param map The tempo map.
417
+ * @returns The span's duration in seconds, never negative.
418
+ * @throws If the map is malformed or the length is negative.
419
+ * @example
420
+ * ```ts
421
+ * import { durationToSeconds } from '@libraz/libcantus';
422
+ * const map = [{ startBeat: 0, bpm: 120 }, { startBeat: 4, bpm: 60 }];
423
+ * durationToSeconds(2, 4, map); // 3 = 2 beats at 120 + 2 beats at 60
424
+ * ```
425
+ * @category Rhythm & Meter
426
+ */
427
+ declare function durationToSeconds(startBeat: number, lengthBeats: number, map: TempoMap): number;
428
+ /**
429
+ * The tempo in effect at a beat.
430
+ *
431
+ * A beat before the first event reads the opening tempo, which is the tempo a
432
+ * pickup is played at.
433
+ *
434
+ * @param beat Position in quarter-note beats.
435
+ * @param map The tempo map.
436
+ * @returns Quarter-note beats per minute.
437
+ * @throws If the map is malformed.
438
+ * @example
439
+ * ```ts
440
+ * import { tempoAt } from '@libraz/libcantus';
441
+ * tempoAt(5, [{ startBeat: 0, bpm: 120 }, { startBeat: 4, bpm: 60 }]); // 60
442
+ * ```
443
+ * @category Rhythm & Meter
444
+ */
445
+ declare function tempoAt(beat: number, map: TempoMap): number;
446
+ /**
447
+ * Convert quarter-note beats to MIDI ticks.
448
+ *
449
+ * Ticks are whole units of a sequencer's grid, so the result is rounded to the
450
+ * nearest tick; a beat that is not on the grid is not representable and comes
451
+ * back quantized.
452
+ *
453
+ * A position before the first downbeat is a negative tick count, which is how a
454
+ * pickup crosses the MIDI boundary and comes back. A position that rounds to
455
+ * the downbeat from below comes back as positive zero: `-0` and `0` are the
456
+ * same tick, and only one of them keys as it under `Object.is`.
457
+ *
458
+ * @param beat Position or length in quarter-note beats.
459
+ * @param ppq Pulses (ticks) per quarter note, e.g. 96, 480, or 960.
460
+ * @returns The whole tick count.
461
+ * @throws If `beat` is not finite, `ppq` is not a positive integer, or the
462
+ * tick count is past the safe integers.
463
+ * @example
464
+ * ```ts
465
+ * import { beatsToTicks } from '@libraz/libcantus';
466
+ * beatsToTicks(1.5, 480); // 720
467
+ * ```
468
+ * @category Rhythm & Meter
469
+ */
470
+ declare function beatsToTicks(beat: number, ppq: number): number;
471
+ /**
472
+ * Convert MIDI ticks to quarter-note beats.
473
+ *
474
+ * @param ticks Whole tick count, negative before the first downbeat.
475
+ * @param ppq Pulses (ticks) per quarter note, e.g. 96, 480, or 960.
476
+ * @returns The position or length in quarter-note beats.
477
+ * @throws If `ticks` is not an integer or `ppq` is not a positive integer.
478
+ * @example
479
+ * ```ts
480
+ * import { ticksToBeats } from '@libraz/libcantus';
481
+ * ticksToBeats(720, 480); // 1.5
482
+ * ```
483
+ * @category Rhythm & Meter
484
+ */
485
+ declare function ticksToBeats(ticks: number, ppq: number): number;
486
+
487
+ /**
488
+ * Tuning and microtonality: frequency conversion, cents, arbitrary equal
489
+ * temperaments (EDO), and just-intonation ratios.
490
+ *
491
+ * The rest of the library reasons in twelve-tone pitch classes, which is a
492
+ * deliberate scope choice for tonal theory. This module is the escape hatch for
493
+ * anyone who needs actual frequencies, cents, non-12 equal temperaments, or the
494
+ * acoustic (just) tuning behind the tempered intervals.
495
+ */
496
+ /**
497
+ * An equal-tempered tuning: a reference pitch and a number of equal divisions of
498
+ * the octave. With `divisions === 12` a step index is an ordinary MIDI number.
499
+ *
500
+ * @category Pitch & Intervals
501
+ */
502
+ type TuningTable = {
503
+ /** Step index (MIDI number when `divisions` is 12) whose frequency is `refFreq`. */
504
+ readonly refStep: number;
505
+ /** Frequency in Hz of `refStep`. */
506
+ readonly refFreq: number;
507
+ /** Equal divisions of the octave (12 standard; e.g. 19 or 31 for microtonal). */
508
+ readonly divisions: number;
509
+ };
510
+ /**
511
+ * Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz.
512
+ *
513
+ * @category Pitch & Intervals
514
+ */
515
+ declare const TWELVE_TET: TuningTable;
516
+ /**
517
+ * Build an equal temperament with `n` divisions of the octave.
518
+ *
519
+ * @param n Divisions of the octave (e.g. 19, 24, 31).
520
+ * @param refFreq Reference frequency in Hz (default 440).
521
+ * @param refStep Step index of the reference (default 69).
522
+ * @returns The tuning.
523
+ * @example
524
+ * ```ts
525
+ * import { edo, frequencyOf } from '@libraz/libcantus';
526
+ * const et19 = edo(19); // { refStep: 69, refFreq: 440, divisions: 19 }
527
+ * frequencyOf(70, et19); // one 19-EDO step above A4
528
+ * ```
529
+ * @category Pitch & Intervals
530
+ */
531
+ declare function edo(n: number, refFreq?: number, refStep?: number): TuningTable;
532
+ /**
533
+ * Frequency in Hz of a step index under a tuning.
534
+ *
535
+ * @param step Step index (a MIDI number under 12-EDO).
536
+ * @param tuning The tuning (default 12-TET).
537
+ * @returns The frequency in Hz.
538
+ * @example
539
+ * ```ts
540
+ * import { frequencyOf } from '@libraz/libcantus';
541
+ * frequencyOf(69); // 440 (A4 in 12-TET)
542
+ * frequencyOf(60); // middle C in Hz
543
+ * ```
544
+ * @category Pitch & Intervals
545
+ */
546
+ declare function frequencyOf(step: number, tuning?: TuningTable): number;
547
+ /**
548
+ * Nearest step index to a frequency under a tuning (the inverse of
549
+ * {@link frequencyOf}, rounded).
550
+ *
551
+ * @param freq Frequency in Hz.
552
+ * @param tuning The tuning (default 12-TET).
553
+ * @returns The nearest step index.
554
+ * @category Pitch & Intervals
555
+ */
556
+ declare function nearestStep(freq: number, tuning?: TuningTable): number;
557
+ /**
558
+ * Step index of a frequency under a tuning, unrounded.
559
+ *
560
+ * The exact inverse of {@link frequencyOf}. {@link nearestStep} rounds it,
561
+ * which discards how far off the pitch actually is — the figure a tuner
562
+ * display, a pitch-bend amount, or an intonation check is built on.
563
+ *
564
+ * @param freq Frequency in Hz.
565
+ * @param tuning The tuning (default 12-TET).
566
+ * @returns The fractional step index.
567
+ * @example
568
+ * ```ts
569
+ * import { stepOf } from '@libraz/libcantus';
570
+ * stepOf(442); // slightly above 69, the step for A440
571
+ * ```
572
+ * @category Pitch & Intervals
573
+ */
574
+ declare function stepOf(freq: number, tuning?: TuningTable): number;
575
+ /**
576
+ * How far a frequency sits from its nearest step, in cents.
577
+ *
578
+ * Positive means sharp of the step, negative flat.
579
+ *
580
+ * @param freq Frequency in Hz.
581
+ * @param tuning The tuning (default 12-TET).
582
+ * @returns The signed deviation in cents.
583
+ * @example
584
+ * ```ts
585
+ * import { centsFromNearestStep } from '@libraz/libcantus';
586
+ * Math.round(centsFromNearestStep(442)); // 8
587
+ * ```
588
+ * @category Pitch & Intervals
589
+ */
590
+ declare function centsFromNearestStep(freq: number, tuning?: TuningTable): number;
591
+ /**
592
+ * Steps spanned by an interval in cents, unrounded — the inverse of
593
+ * {@link centsOfSteps}.
594
+ *
595
+ * @param cents The interval in cents.
596
+ * @param tuning The tuning (default 12-TET).
597
+ * @returns The fractional step count.
598
+ * @category Pitch & Intervals
599
+ */
600
+ declare function stepsOfCents(cents: number, tuning?: TuningTable): number;
601
+ /**
602
+ * The frequency ratio an interval in cents spans — the inverse of
603
+ * {@link ratioToCents}.
604
+ *
605
+ * Multiply a frequency by this to move it by that many cents, which is how a
606
+ * cents offset (a pitch-bend spec, a tuning table entry) is applied.
607
+ *
608
+ * @param cents The interval in cents.
609
+ * @returns The frequency ratio.
610
+ * @example
611
+ * ```ts
612
+ * import { centsToRatio } from '@libraz/libcantus';
613
+ * 440 * centsToRatio(14); // A440 raised by 14 cents
614
+ * ```
615
+ * @category Pitch & Intervals
616
+ */
617
+ declare function centsToRatio(cents: number): number;
618
+ /**
619
+ * Interval in cents between two frequencies.
620
+ *
621
+ * @param a Lower/first frequency in Hz.
622
+ * @param b Upper/second frequency in Hz.
623
+ * @returns Cents from `a` to `b` (negative if `b` is lower).
624
+ * @category Pitch & Intervals
625
+ */
626
+ declare function centsBetweenFreq(a: number, b: number): number;
627
+ /**
628
+ * Cents spanned by a number of equal-temperament steps.
629
+ *
630
+ * @param steps Number of steps.
631
+ * @param tuning The tuning (default 12-TET).
632
+ * @returns The cents.
633
+ * @category Pitch & Intervals
634
+ */
635
+ declare function centsOfSteps(steps: number, tuning?: TuningTable): number;
636
+ /**
637
+ * Cents of a frequency ratio, e.g. `ratioToCents(3, 2)` ≈ 701.955 for the just
638
+ * perfect fifth.
639
+ *
640
+ * @param numerator Ratio numerator.
641
+ * @param denominator Ratio denominator.
642
+ * @returns The interval in cents.
643
+ * @category Pitch & Intervals
644
+ */
645
+ declare function ratioToCents(numerator: number, denominator: number): number;
646
+ /**
647
+ * Five-limit just-intonation ratios for the twelve interval classes above a
648
+ * unison, indexed by semitone class (0..12).
649
+ *
650
+ * @category Pitch & Intervals
651
+ */
652
+ declare const JUST_RATIOS: Readonly<Record<0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12, readonly [number, number]>>;
653
+ /**
654
+ * Cents by which a five-limit just interval departs from its 12-TET tempering
655
+ * (positive means the just interval is wider).
656
+ *
657
+ * @param semitoneClass Semitone class in [0, 12].
658
+ * @returns The deviation in cents.
659
+ * @throws If `semitoneClass` is not an integer in [0, 12].
660
+ * @category Pitch & Intervals
661
+ */
662
+ declare function justDeviationCents(semitoneClass: number): number;
663
+
664
+ 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 };
665
+ 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 };