@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,804 @@
1
+ /**
2
+ * Every playing technique a note can carry, in declaration order.
3
+ *
4
+ * These name intent, not a rendering: how `flam` becomes a grace stroke or
5
+ * `slide` becomes pitch bend is the caller's decision, because it depends on the
6
+ * sampler, key switches, and controller layout in use. Carrying the intent
7
+ * instead of a baked note pair is what lets any phrase be flammed, ghosted, or
8
+ * muted without the generator having to know how it will be voiced.
9
+ *
10
+ * @category Core
11
+ */
12
+ declare const ARTICULATIONS: readonly ["accent", "ghost", "staccato", "legato", "slide", "hammer", "mute", "flam", "drag", "roll", "choke", "open"];
13
+ /**
14
+ * How a note is played, independent of its pitch and length.
15
+ *
16
+ * @category Core
17
+ */
18
+ type Articulation = (typeof ARTICULATIONS)[number];
19
+
20
+ /**
21
+ * A key/scale definition anchored on a root pitch class.
22
+ *
23
+ * `modeMask12` is a 12-bit mask where bit `n` set means the pitch class
24
+ * `(rootPc + n) % 12` belongs to the scale. Bit 0 (the root) is always set;
25
+ * {@link maskFromOffsets} enforces this so the root is always a scale tone.
26
+ *
27
+ * @category Core
28
+ */
29
+ type KeyScale = {
30
+ rootPc: number;
31
+ modeMask12: number;
32
+ };
33
+ /**
34
+ * A single sounding note on a beat-indexed timeline: an absolute MIDI pitch, an
35
+ * onset and duration measured in quarter-note beats, and an optional MIDI
36
+ * velocity. This is the library-wide interchange shape for note events read
37
+ * from or written to a DAW/MIDI track; the harmonizer's `MelodyNote` and the
38
+ * analysis `VoiceNote` are specializations of it.
39
+ *
40
+ * @category Core
41
+ */
42
+ type NoteEvent = {
43
+ /** MIDI pitch in [0, 127] (middle C = 60). */
44
+ pitch: number;
45
+ /**
46
+ * Onset in quarter-note beats, absolute from the start of the timeline, and
47
+ * unbounded below: beat 0 is the first downbeat, so a pickup sounds before it
48
+ * and is written at a negative onset, in the bar numbered -1. Shifting the
49
+ * whole timeline a bar later instead would move every strong beat with it,
50
+ * and the upbeat would then be analyzed as a downbeat. A caller that knows
51
+ * how long its pickup is narrows the bound with
52
+ * {@link NoteEventAssertOptions.minStartBeat}.
53
+ */
54
+ startBeat: number;
55
+ /** Duration in quarter-note beats. */
56
+ durationBeat: number;
57
+ /** MIDI velocity in [0, 127], when known. */
58
+ velocity?: number;
59
+ /**
60
+ * How the note is played, when the writer had an intent to record. The
61
+ * library carries the intent only: turning `slide` into pitch bend or `ghost`
62
+ * into a velocity floor depends on the instrument and controller layout at
63
+ * the far end, so it is the reader's decision. Optional, so a reader that
64
+ * knows nothing of articulation reads the note exactly as before.
65
+ */
66
+ articulation?: Articulation;
67
+ };
68
+
69
+ /**
70
+ * The library's error taxonomy.
71
+ *
72
+ * Every failure this library raises falls into one of three kinds, and the kind
73
+ * decides what a caller can do about it. Batch-voicing a lead sheet, for
74
+ * instance, has to tell "fix the input" apart from "loosen the constraints",
75
+ * and a message string is not a contract.
76
+ *
77
+ * The classes extend the built-in error types a caller would otherwise catch —
78
+ * a rejected argument is still a `RangeError` — so the `code` narrows an
79
+ * existing category rather than replacing it.
80
+ */
81
+ /**
82
+ * What kind of failure an error reports.
83
+ *
84
+ * - `INVALID_INPUT`: an argument is malformed or out of range. The caller's
85
+ * input must change.
86
+ * - `NO_SOLUTION`: the input is valid but nothing satisfies the constraints.
87
+ * The constraints must change, or the failure must be accepted.
88
+ * - `BUDGET_EXCEEDED`: the requested work is larger than the synchronous
89
+ * generation budget. The request must be smaller, or the budget larger.
90
+ *
91
+ * @category Core
92
+ */
93
+ type LibcantusErrorCode = 'INVALID_INPUT' | 'NO_SOLUTION' | 'BUDGET_EXCEEDED';
94
+ /**
95
+ * Any error this library raises, as a union of its three classes.
96
+ *
97
+ * The type a non-throwing entry point reports its failure as: a caller that
98
+ * holds one of these already knows it carries a {@link LibcantusErrorCode} and
99
+ * a message worth showing.
100
+ *
101
+ * @category Core
102
+ */
103
+ type LibcantusError = InvalidInputError | NoSolutionError | BudgetExceededError;
104
+ /**
105
+ * The outcome of a parse that reports failure instead of throwing it.
106
+ *
107
+ * A text field is parsed on every keystroke, and most of those keystrokes are
108
+ * halfway through a valid symbol, so failure is the normal case rather than an
109
+ * exceptional one. The error travels in the result — not as `null` — because an
110
+ * input field has to say what is wrong with what was typed.
111
+ *
112
+ * @typeParam T The value a successful parse produces.
113
+ * @category Core
114
+ * @example
115
+ * ```ts
116
+ * import { tryParseChordSymbol } from '@libraz/libcantus';
117
+ * const result = tryParseChordSymbol('Cmaj');
118
+ * const label = result.ok ? result.value.quality : result.error.message;
119
+ * ```
120
+ */
121
+ type ParseResult<T> = {
122
+ ok: true;
123
+ value: T;
124
+ } | {
125
+ ok: false;
126
+ error: LibcantusError;
127
+ };
128
+ /**
129
+ * A rejected argument: malformed, out of range, or naming something unknown.
130
+ *
131
+ * @category Core
132
+ */
133
+ declare class InvalidInputError extends RangeError {
134
+ readonly code: "INVALID_INPUT";
135
+ readonly name = "InvalidInputError";
136
+ }
137
+ /**
138
+ * A valid request with no answer: no voicing fits the given ranges, no chord
139
+ * matches the pitches, no preset claims the style.
140
+ *
141
+ * @category Core
142
+ */
143
+ declare class NoSolutionError extends Error {
144
+ readonly code: "NO_SOLUTION";
145
+ readonly name = "NoSolutionError";
146
+ /**
147
+ * Where in a sequence the failure occurred, when the operation was working
148
+ * through one — the chord index of a progression, say.
149
+ */
150
+ readonly at: number | undefined;
151
+ constructor(message: string, options?: {
152
+ at?: number;
153
+ });
154
+ }
155
+ /**
156
+ * Work that would exceed the synchronous generation budget.
157
+ *
158
+ * @category Core
159
+ */
160
+ declare class BudgetExceededError extends RangeError {
161
+ readonly code: "BUDGET_EXCEEDED";
162
+ readonly name = "BudgetExceededError";
163
+ }
164
+ /**
165
+ * Whether a caught value is one of this library's coded errors.
166
+ *
167
+ * @param value The caught value.
168
+ * @returns True when it carries a {@link LibcantusErrorCode}.
169
+ * @example
170
+ * ```ts
171
+ * import { isLibcantusError, voiceChord, parseChordSymbol } from '@libraz/libcantus';
172
+ * try {
173
+ * voiceChord(parseChordSymbol('C'), { ranges: [] });
174
+ * } catch (error) {
175
+ * if (isLibcantusError(error) && error.code === 'NO_SOLUTION') {
176
+ * // loosen the constraints rather than blaming the input
177
+ * }
178
+ * }
179
+ * ```
180
+ * @category Core
181
+ */
182
+ declare function isLibcantusError(value: unknown): value is InvalidInputError | NoSolutionError | BudgetExceededError;
183
+
184
+ /**
185
+ * Note-name notation systems.
186
+ *
187
+ * A pitch has one identity but many written names: the note an English score
188
+ * calls `G#` is `gis` in German, `嬰ト` in Japanese and `sol diesis` in Italian.
189
+ * This module holds each system's table — letters, accidental affixes and mode
190
+ * words — so a name can be read and written in the system a source actually
191
+ * uses, and so a name of unknown origin can be attributed to one.
192
+ *
193
+ * The tables live together because attribution needs them together: `B` is a B
194
+ * natural in English but a B flat in German, and only a table that knows both
195
+ * can say so.
196
+ */
197
+
198
+ /**
199
+ * A system of written note names.
200
+ *
201
+ * - `english`: C D E F G A B, `#` sharp and `b` flat (`C#`, `Bb`, `F##`).
202
+ * - `german`: C D E F G A H, `-is` sharp and `-es` flat (`cis`, `des`), with B
203
+ * for B flat and H for B natural.
204
+ * - `japanese`: the katakana 音名 ハ ニ ホ ヘ ト イ ロ, prefixed 嬰 sharp and
205
+ * 変 flat.
206
+ * - `italian`: the solfège syllables do re mi fa sol la si, followed by
207
+ * `diesis` or `bemolle`.
208
+ * - `fixedDo`: the same syllables read as fixed-do note names; identical to
209
+ * `italian`, and named separately because callers ask for it by that name.
210
+ *
211
+ * @category Pitch & Intervals
212
+ */
213
+ type NoteNameSystem = 'english' | 'german' | 'japanese' | 'italian' | 'fixedDo';
214
+ /**
215
+ * Which notation system to read or write a name in.
216
+ *
217
+ * @category Pitch & Intervals
218
+ */
219
+ type NoteNameOptions = {
220
+ /**
221
+ * The system. Omitted on parsing, the system is detected from the name
222
+ * itself; omitted on formatting, the name is written in English.
223
+ */
224
+ system?: NoteNameSystem;
225
+ };
226
+ /**
227
+ * A key named the way a score names it: a spelled tonic and a mode.
228
+ *
229
+ * This is what a key *name* carries. It is deliberately not a key/scale: a name
230
+ * fixes the tonic's spelling and says major or minor, and nothing more.
231
+ *
232
+ * @category Scales
233
+ */
234
+ type KeyName = {
235
+ /** The spelled tonic, without an octave. */
236
+ tonic: Note;
237
+ /** Which of the two modes the name gives. */
238
+ mode: 'major' | 'minor';
239
+ };
240
+ /**
241
+ * The notation system a note name or key name is written in.
242
+ *
243
+ * A name several systems could read is attributed to the first of English,
244
+ * German, Japanese, Italian that reads it — so `B` is the English B natural,
245
+ * and German is chosen only for a name carrying a German-only cue (`H`, an
246
+ * `-is`/`-es` ending, or `dur`/`moll`). Because the fixed-do syllables are the
247
+ * Italian ones, detection reports `'italian'` for them; `'fixedDo'` is only ever
248
+ * a system a caller asks for by name.
249
+ *
250
+ * @param text The note name or key name.
251
+ * @returns The system that reads it.
252
+ * @throws If no system reads the name, or the name mixes two systems — a German
253
+ * tonic under an English mode word, say.
254
+ * @example
255
+ * ```ts
256
+ * import { detectNoteNameSystem } from '@libraz/libcantus';
257
+ * detectNoteNameSystem('B'); // 'english' — never the German B flat
258
+ * detectNoteNameSystem('gis moll'); // 'german'
259
+ * detectNoteNameSystem('嬰ト短調'); // 'japanese'
260
+ * ```
261
+ * @category Pitch & Intervals
262
+ */
263
+ declare function detectNoteNameSystem(text: string): NoteNameSystem;
264
+
265
+ /**
266
+ * Pitch spelling: letter-name notes, enharmonic-aware conversion, and spelled
267
+ * intervals.
268
+ *
269
+ * The rest of the library works in pitch classes (0..11), which cannot tell a
270
+ * G# from an Ab or an augmented fourth from a diminished fifth. This module adds
271
+ * an explicit spelling layer — a note is a diatonic letter plus a chromatic
272
+ * alteration — so interval quality (P/M/m/A/d) and enharmonic identity are
273
+ * preserved.
274
+ */
275
+
276
+ /**
277
+ * A spelled note: a diatonic letter, a chromatic alteration, and an optional
278
+ * octave.
279
+ *
280
+ * - `letter` is 0..6 for C..B.
281
+ * - `alter` is the number of semitones of alteration: -2 double-flat, -1 flat,
282
+ * 0 natural, +1 sharp, +2 double-sharp.
283
+ * - `octave` follows scientific pitch notation (middle C = C4 = MIDI 60). When
284
+ * absent, the note denotes a bare pitch class.
285
+ *
286
+ * @category Pitch & Intervals
287
+ */
288
+ type Note = {
289
+ letter: number;
290
+ alter: number;
291
+ octave?: number;
292
+ };
293
+ /**
294
+ * The quality label of a spelled interval: perfect, major, minor, or one or
295
+ * more augmentations or diminutions.
296
+ *
297
+ * This names how an interval is *spelled*. It is a different notion from
298
+ * {@link ConsonanceClass}, which classifies how an interval *sounds* against
299
+ * another voice.
300
+ *
301
+ * @see {@link ConsonanceClass}
302
+ * @category Pitch & Intervals
303
+ */
304
+ type IntervalQualityLabel = 'P' | 'M' | 'm' | `A${string}` | `d${string}`;
305
+ /**
306
+ * A spelled interval: a diatonic number, a quality label, and its semitone span.
307
+ *
308
+ * @category Pitch & Intervals
309
+ */
310
+ type SpelledInterval = {
311
+ /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
312
+ number: number;
313
+ /** Quality label: 'P', 'M', 'm', or repeated 'A'/'d' for (multiply) aug/dim. */
314
+ quality: IntervalQualityLabel;
315
+ /** Signed semitone distance from the first note to the second. */
316
+ semitones: number;
317
+ /**
318
+ * Whether the diatonic letters move down.
319
+ *
320
+ * Always present, so the direction of a written-down interval is not
321
+ * something a reader can lose: data rebuilt without the key would otherwise
322
+ * come back ascending with nothing to say it had changed. Every producer
323
+ * decides it, and the compiler asks each one to.
324
+ *
325
+ * Not redundant with the sign of the span: a descending unison spans zero
326
+ * semitones, and a letter can rise while the pitch falls — `dd2` climbs a
327
+ * letter and loses a semitone.
328
+ */
329
+ descending: boolean;
330
+ };
331
+ /**
332
+ * Reduce a MIDI pitch, a bare pitch class, or any signed offset to a pitch
333
+ * class in [0, 11].
334
+ *
335
+ * This is the library's single definition of pitch-class arithmetic: every
336
+ * layer routes through it so a fractional pitch reduces the same way
337
+ * everywhere. A non-integral input is rounded to the nearest semitone first, so
338
+ * a microtonal 60.6 reads as C# rather than C.
339
+ *
340
+ * @param value A MIDI pitch, pitch class, or signed semitone offset.
341
+ * @returns The pitch class in [0, 11].
342
+ * @example
343
+ * ```ts
344
+ * import { pitchClassOf } from '@libraz/libcantus';
345
+ * pitchClassOf(61); // 1
346
+ * pitchClassOf(-1); // 11
347
+ * pitchClassOf(60.6); // 1
348
+ * ```
349
+ * @category Pitch & Intervals
350
+ */
351
+ declare function pitchClassOf(value: number): number;
352
+ /**
353
+ * Reduce a letter number or letter offset to a diatonic letter in [0, 6]
354
+ * (0 = C .. 6 = B).
355
+ *
356
+ * @param value A letter number or signed letter offset.
357
+ * @returns The diatonic letter in [0, 6].
358
+ * @category Pitch & Intervals
359
+ */
360
+ declare function diatonicLetterOf(value: number): number;
361
+ /**
362
+ * The pitch class of a diatonic letter with no accidental (C = 0, D = 2, ...).
363
+ *
364
+ * @param letter A letter number or signed letter offset; reduced to [0, 6].
365
+ * @returns The natural pitch class of that letter.
366
+ * @category Pitch & Intervals
367
+ */
368
+ declare function naturalPitchClassOf(letter: number): number;
369
+ /**
370
+ * Parse a note name into a {@link Note}, in any supported notation system.
371
+ *
372
+ * English (the default when a name could be read in more than one system)
373
+ * accepts a letter (case-insensitive) followed by any number of same-direction
374
+ * accidentals and an optional octave, e.g. `"C"`, `"C#4"`, `"Bb"`, `"F##3"`,
375
+ * `"Ebb2"`. Both `#` and `x` (double-sharp) are accepted for sharps; `b` for
376
+ * flats. Mixing sharps and flats (e.g. `"C#b"`) is rejected.
377
+ *
378
+ * Without a `system` the name is attributed by {@link detectNoteNameSystem},
379
+ * which reads a name any two systems could claim as English: `"B"` is the B
380
+ * natural, never the German B flat. German is chosen only for a German-only
381
+ * name such as `"H"`, `"fis"` or `"es"`.
382
+ *
383
+ * A scientific octave may follow the name in every system (`"gis4"`,
384
+ * `"嬰ト4"`), which is what makes formatting and parsing exact inverses for an
385
+ * octave-bearing note.
386
+ *
387
+ * @param text The note name.
388
+ * @param opts `system` reads the name in that notation system instead of
389
+ * detecting it.
390
+ * @returns The parsed note.
391
+ * @throws If the text is not a valid note in the given (or detected) system.
392
+ * Use {@link tryParseNote} where failure is ordinary, such as a note field
393
+ * read on every keystroke.
394
+ * @example
395
+ * ```ts
396
+ * import { parseNote, noteToMidi, noteToPitchClass } from '@libraz/libcantus';
397
+ * noteToMidi(parseNote('C#4')); // 61
398
+ * noteToPitchClass(parseNote('gis')); // 8 — the German G sharp
399
+ * noteToPitchClass(parseNote('B', { system: 'german' })); // 10 — the German B flat
400
+ * ```
401
+ * @category Pitch & Intervals
402
+ */
403
+ declare function parseNote(text: string, opts?: NoteNameOptions): Note;
404
+ /**
405
+ * Parse a note name, reporting failure instead of throwing it.
406
+ *
407
+ * The same reading as {@link parseNote} — that function is this one with its
408
+ * error thrown — for the callers where a name that does not parse yet is the
409
+ * normal state of the input rather than a fault.
410
+ *
411
+ * @param text The note name.
412
+ * @param opts `system` reads the name in that notation system instead of
413
+ * detecting it.
414
+ * @returns The note, or the error explaining why the text is not one.
415
+ * @example
416
+ * ```ts
417
+ * import { tryParseNote } from '@libraz/libcantus';
418
+ * const result = tryParseNote('C#4');
419
+ * result.ok ? result.value.letter : result.error.message;
420
+ * ```
421
+ * @category Pitch & Intervals
422
+ */
423
+ declare function tryParseNote(text: string, opts?: NoteNameOptions): ParseResult<Note>;
424
+ /**
425
+ * Render a {@link Note} as a note name, in any supported notation system.
426
+ *
427
+ * The inverse of {@link parseNote} when both are given the same `system`,
428
+ * including double accidentals and octaves. Without one, {@link parseNote}
429
+ * detects the system and reads a bare `B` as the English B natural, so a German
430
+ * B flat written as `'b'` does not survive a round trip that names no system.
431
+ *
432
+ * @param note The note to format.
433
+ * @param opts `system` writes the name in that notation system instead of
434
+ * English.
435
+ * @returns The note name, including the octave when present.
436
+ * @example
437
+ * ```ts
438
+ * import { formatNote, parseNote } from '@libraz/libcantus';
439
+ * formatNote(parseNote('C#4')); // 'C#4'
440
+ * formatNote(parseNote('G#'), { system: 'german' }); // 'gis'
441
+ * formatNote(parseNote('G#'), { system: 'japanese' }); // '嬰ト'
442
+ * ```
443
+ * @category Pitch & Intervals
444
+ */
445
+ declare function formatNote(note: Note, opts?: NoteNameOptions): string;
446
+ /**
447
+ * Parse a key name such as `'C major'`, `'gis moll'` or `'嬰ト短調'`.
448
+ *
449
+ * The name is a tonic followed by a mode word, in any of the supported
450
+ * notation systems; German also accepts its hyphenated form (`'gis-Moll'`).
451
+ * Without a `system` the name is attributed by {@link detectNoteNameSystem},
452
+ * so a mode word is itself enough to pick one: `'B dur'` is B flat major while
453
+ * `'B major'` is B major.
454
+ *
455
+ * German carries the mode twice, in the word and in the case of the tonic
456
+ * (`C dur`, `c moll`). When the two disagree the word wins — `'C moll'` is C
457
+ * minor — because the word is what the writer said and the case only what they
458
+ * typed. A German name with no mode word is decided by its case alone
459
+ * (`'gis'` is G sharp minor, `'Gis'` G sharp major); a bare tonic in any other
460
+ * system names a major key.
461
+ *
462
+ * @param text The key name.
463
+ * @param opts `system` reads the name in that notation system instead of
464
+ * detecting it.
465
+ * @returns The spelled tonic and the mode.
466
+ * @throws If the text is not a key name in the given (or detected) system, if
467
+ * it mixes two systems, or if the tonic carries an octave. Use
468
+ * {@link tryParseKeyName} where failure is ordinary, such as a key field read
469
+ * on every keystroke.
470
+ * @example
471
+ * ```ts
472
+ * import { formatNote, parseKeyName } from '@libraz/libcantus';
473
+ * const key = parseKeyName('gis moll');
474
+ * formatNote(key.tonic); // 'G#'
475
+ * key.mode; // 'minor'
476
+ * ```
477
+ * @category Scales
478
+ */
479
+ declare function parseKeyName(text: string, opts?: NoteNameOptions): KeyName;
480
+ /**
481
+ * Parse a key name, reporting failure instead of throwing it.
482
+ *
483
+ * The same reading as {@link parseKeyName} — that function is this one with its
484
+ * error thrown — for the callers where a name that does not parse yet is the
485
+ * normal state of the input rather than a fault.
486
+ *
487
+ * @param text The key name.
488
+ * @param opts `system` reads the name in that notation system instead of
489
+ * detecting it.
490
+ * @returns The key, or the error explaining why the text is not one.
491
+ * @example
492
+ * ```ts
493
+ * import { tryParseKeyName } from '@libraz/libcantus';
494
+ * const result = tryParseKeyName('gis moll');
495
+ * result.ok ? result.value.mode : result.error.message; // 'minor'
496
+ * ```
497
+ * @category Scales
498
+ */
499
+ declare function tryParseKeyName(text: string, opts?: NoteNameOptions): ParseResult<KeyName>;
500
+ /**
501
+ * Render a spelled tonic and a mode as a key name.
502
+ *
503
+ * The inverse of {@link parseKeyName}. German is written the way it is read,
504
+ * with the mode in the case of the tonic as well as in the word.
505
+ *
506
+ * @param key The spelled tonic and mode; any octave on the tonic is dropped,
507
+ * since a key has no register.
508
+ * @param opts `system` writes the name in that notation system instead of
509
+ * English.
510
+ * @returns The key name.
511
+ * @throws If the tonic or the mode is not valid.
512
+ * @example
513
+ * ```ts
514
+ * import { formatKeyName, parseNote } from '@libraz/libcantus';
515
+ * formatKeyName({ tonic: parseNote('G#'), mode: 'minor' }); // 'G# minor'
516
+ * formatKeyName({ tonic: parseNote('G#'), mode: 'minor' }, { system: 'german' }); // 'gis moll'
517
+ * ```
518
+ * @category Scales
519
+ */
520
+ declare function formatKeyName(key: KeyName, opts?: NoteNameOptions): string;
521
+ /**
522
+ * Pitch class (0..11) of a note, ignoring octave.
523
+ *
524
+ * @param note The note.
525
+ * @returns The pitch class.
526
+ * @example
527
+ * ```ts
528
+ * import { noteToPitchClass, parseNote } from '@libraz/libcantus';
529
+ * noteToPitchClass(parseNote('Db')); // 1
530
+ * ```
531
+ * @category Pitch & Intervals
532
+ */
533
+ declare function noteToPitchClass(note: Note): number;
534
+ /**
535
+ * MIDI number of a note (middle C = C4 = 60).
536
+ *
537
+ * @param note The note; must carry an octave.
538
+ * @returns The MIDI number.
539
+ * @throws If the note has no octave.
540
+ * @example
541
+ * ```ts
542
+ * import { noteToMidi, parseNote } from '@libraz/libcantus';
543
+ * noteToMidi(parseNote('A4')); // 69
544
+ * ```
545
+ * @category Pitch & Intervals
546
+ */
547
+ declare function noteToMidi(note: Note): number;
548
+ /**
549
+ * Name a MIDI number as a {@link Note}, choosing sharp or flat spelling.
550
+ *
551
+ * The input is rounded to the nearest integer but is not clamped to the MIDI
552
+ * range 0..127: out-of-range values extrapolate linearly (e.g. `-1` -> `B-2`,
553
+ * `128` -> `G#9`) and remain an exact inverse of {@link noteToMidi}.
554
+ *
555
+ * @param midi The MIDI number.
556
+ * @param spelling Whether to prefer sharps or flats for black keys.
557
+ * @returns The spelled note, with octave.
558
+ * @throws If `spelling` is neither `'sharp'` nor `'flat'`; a name the table does
559
+ * not carry would otherwise be spelled as one of them without saying which.
560
+ * @example
561
+ * ```ts
562
+ * import { midiToNote, formatNote } from '@libraz/libcantus';
563
+ * formatNote(midiToNote(61)); // 'C#4'
564
+ * formatNote(midiToNote(61, 'flat')); // 'Db4'
565
+ * ```
566
+ * @category Pitch & Intervals
567
+ */
568
+ declare function midiToNote(midi: number, spelling?: 'sharp' | 'flat'): Note;
569
+ /**
570
+ * Transpose a note by a signed number of semitones, keeping its spelling.
571
+ *
572
+ * The letter moves by the diatonic distance of the conventional interval for
573
+ * that many semitones and the accidental is recomputed for the new letter, so
574
+ * enharmonic identity survives: `Ab4` up a major second is `Bb4`, not `A#4`, and
575
+ * the operation is an exact inverse of itself. An octave-less note stays
576
+ * octave-less.
577
+ *
578
+ * A bare semitone count cannot distinguish an augmented fourth from a diminished
579
+ * fifth; pass `spelling` to override the letter distance when the enharmonic
580
+ * choice matters.
581
+ *
582
+ * @param note The note to transpose.
583
+ * @param semitones The signed semitone offset.
584
+ * @param opts `spelling` forces the result onto the sharp or flat side instead
585
+ * of following the source note's letter.
586
+ * @returns The transposed note.
587
+ * @example
588
+ * ```ts
589
+ * import { transposeNote, formatNote, parseNote } from '@libraz/libcantus';
590
+ * formatNote(transposeNote(parseNote('Ab4'), 2)); // 'Bb4'
591
+ * formatNote(transposeNote(parseNote('Ab4'), 2, { spelling: 'sharp' })); // 'A#4'
592
+ * ```
593
+ * @category Pitch & Intervals
594
+ */
595
+ declare function transposeNote(note: Note, semitones: number, opts?: {
596
+ spelling?: 'sharp' | 'flat';
597
+ }): Note;
598
+ /**
599
+ * The semitone span of the interval named by a diatonic number and a quality.
600
+ *
601
+ * The inverse of the quality derivation in {@link spelledInterval}: it turns a
602
+ * name back into a distance, which is what transposing by a named interval or
603
+ * parsing one from text needs.
604
+ *
605
+ * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
606
+ * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
607
+ * @returns The signed semitone span the name covers when its letters ascend.
608
+ * Nearly every name spans upward, but a second narrowed far enough crosses
609
+ * zero while its letters still rise — C# up to Dbb is a doubly diminished
610
+ * second spanning -1 — and the sign is what keeps that name reading as the
611
+ * same interval a measurement of those two notes reports.
612
+ * @throws If the quality cannot apply to the number, such as a major fifth or a
613
+ * diminished unison.
614
+ * @example
615
+ * ```ts
616
+ * import { intervalSemitones } from '@libraz/libcantus';
617
+ * intervalSemitones(5, 'P'); // 7
618
+ * ```
619
+ * @category Pitch & Intervals
620
+ */
621
+ declare function intervalSemitones(numberValue: number, quality: IntervalQualityLabel): number;
622
+ /**
623
+ * Parse an interval name such as `'P5'`, `'m3'`, `'AA4'`, or `'-m3'`.
624
+ *
625
+ * A leading `'-'` names the same interval taken downward: the span is negated
626
+ * and `descending` is set. The flag is not redundant with the sign — a
627
+ * descending unison spans zero semitones, so only the flag records that the
628
+ * letters move down.
629
+ *
630
+ * @param name The interval name: an optional `'-'`, a quality label, and a
631
+ * diatonic number. Surrounding whitespace is ignored.
632
+ * @returns The spelled interval. `descending` is always present, `false` for an
633
+ * ascending name, and the span is the one {@link intervalSemitones} reports —
634
+ * negative for the rare second narrowed past a zero span.
635
+ * @throws If the name is not a quality label followed by a number, or the two
636
+ * cannot describe the same interval. Use {@link tryParseInterval} where
637
+ * failure is ordinary, such as an interval field read on every keystroke.
638
+ * @example
639
+ * ```ts
640
+ * import { parseInterval } from '@libraz/libcantus';
641
+ * parseInterval('m3'); // { number: 3, quality: 'm', semitones: 3, descending: false }
642
+ * parseInterval('-m3'); // { number: 3, quality: 'm', semitones: -3, descending: true }
643
+ * ```
644
+ * @category Pitch & Intervals
645
+ */
646
+ declare function parseInterval(name: string): SpelledInterval;
647
+ /**
648
+ * Parse an interval name, reporting failure instead of throwing it.
649
+ *
650
+ * The same reading as {@link parseInterval} — that function is this one with
651
+ * its error thrown — for the callers where a name that does not parse yet is
652
+ * the normal state of the input rather than a fault.
653
+ *
654
+ * @param name The interval name.
655
+ * @returns The interval, or the error explaining why the text is not one.
656
+ * @example
657
+ * ```ts
658
+ * import { tryParseInterval } from '@libraz/libcantus';
659
+ * const result = tryParseInterval('M5');
660
+ * result.ok ? result.value.semitones : result.error.message; // a fifth cannot be major
661
+ * ```
662
+ * @category Pitch & Intervals
663
+ */
664
+ declare function tryParseInterval(name: string): ParseResult<SpelledInterval>;
665
+ /**
666
+ * Anything that names a spelled interval: an interval name, plain interval
667
+ * data, or a value that serializes to interval data such as the `Interval`
668
+ * class.
669
+ *
670
+ * @category Pitch & Intervals
671
+ */
672
+ type IntervalLike = string | IntervalData | {
673
+ /** The interval data this value stands for. */
674
+ toJSON(): IntervalData;
675
+ };
676
+ /**
677
+ * Interval data as a caller may write it, with the direction optional.
678
+ *
679
+ * Deliberately wider than {@link SpelledInterval}: a caller hands in what they
680
+ * have, including data written before the direction travelled with it, and
681
+ * {@link toSpelledInterval} decides what is missing. Narrowing the input to the
682
+ * resolved shape would refuse the very data the resolver exists to repair.
683
+ *
684
+ * @category Pitch & Intervals
685
+ */
686
+ type IntervalData = Omit<SpelledInterval, 'descending'> & {
687
+ /** Whether the letters move down; read from the span and quality when absent. */
688
+ descending?: boolean;
689
+ };
690
+ /**
691
+ * Resolve any interval-shaped value to plain {@link SpelledInterval} data.
692
+ *
693
+ * This is what lets an entry point accept an interval name, the plain data the
694
+ * pitch module returns, or an `Interval` instance without every caller
695
+ * branching on the form. An instance is accepted through its `toJSON` method
696
+ * rather than by its type, because the core layer cannot import the model layer
697
+ * that defines the class.
698
+ *
699
+ * @param value An interval name, plain interval data, or a value whose `toJSON`
700
+ * returns interval data.
701
+ * @returns The validated interval data, always carrying `descending`, `false`
702
+ * for an interval that ascends.
703
+ * @throws If the value is not interval-shaped, or its number, quality, and span
704
+ * do not describe the same interval.
705
+ * @example
706
+ * ```ts
707
+ * import { toSpelledInterval } from '@libraz/libcantus';
708
+ * toSpelledInterval('P5'); // { number: 5, quality: 'P', semitones: 7, descending: false }
709
+ * toSpelledInterval({ number: 5, quality: 'P', semitones: -7 });
710
+ * // { number: 5, quality: 'P', semitones: -7, descending: true }
711
+ * ```
712
+ * @category Pitch & Intervals
713
+ */
714
+ declare function toSpelledInterval(value: IntervalLike): SpelledInterval;
715
+ /**
716
+ * Anything that names a spelled note: a note name, plain note data, a MIDI
717
+ * number, or a value that serializes to note data such as the `Note` class.
718
+ *
719
+ * @category Pitch & Intervals
720
+ */
721
+ type NoteLike = string | number | Note | {
722
+ /** The note data this value stands for. */
723
+ toJSON(): Note;
724
+ };
725
+ /**
726
+ * Resolve any note-shaped value to plain {@link Note} data.
727
+ *
728
+ * The counterpart of {@link toSpelledInterval} for notes: an entry point takes
729
+ * whatever form the caller has — the name a text field holds, the MIDI number a
730
+ * device sends, the data the pitch module returns, or a `Note` instance — and
731
+ * gets one shape back. An instance is accepted through its `toJSON` method
732
+ * rather than by its type, because the core layer cannot import the model layer
733
+ * that defines the class.
734
+ *
735
+ * A number is read as MIDI and spelled with sharps, the same reading
736
+ * {@link midiToNote} takes by default. Where a key is known the caller spells
737
+ * it there instead — `spellPitch` reads the key — because no single default
738
+ * suits both a G# in E major and an Ab in Eb major.
739
+ *
740
+ * @param value A note name, a MIDI number, plain note data, or a value whose
741
+ * `toJSON` returns note data.
742
+ * @returns The validated note data, carrying `octave` only when the value has
743
+ * one.
744
+ * @throws If the value is not note-shaped, or its letter, alteration, or octave
745
+ * fall outside the range a spelled note holds.
746
+ * @example
747
+ * ```ts
748
+ * import { toNoteData } from '@libraz/libcantus';
749
+ * toNoteData('Eb4'); // { letter: 2, alter: -1, octave: 4 }
750
+ * toNoteData(60); // { letter: 0, alter: 0, octave: 4 }
751
+ * ```
752
+ * @category Pitch & Intervals
753
+ */
754
+ declare function toNoteData(value: NoteLike): Note;
755
+ /**
756
+ * Transpose a note by a spelled interval, keeping the spelling the interval
757
+ * names.
758
+ *
759
+ * Unlike {@link transposeNote}, which picks a letter from the semitone count,
760
+ * the diatonic number decides the letter here: transposing C by an augmented
761
+ * second gives D#, not Eb.
762
+ *
763
+ * Both arguments are taken in whatever form the caller holds them — the text a
764
+ * field carries, the plain data the library returns, or the class that wraps
765
+ * it — as the class mirror of this operation already did.
766
+ *
767
+ * @param given The note to transpose: a name, a MIDI number, plain note data,
768
+ * or a `Note`.
769
+ * @param named The interval to apply: a name, plain interval data, or an
770
+ * `Interval`. A negative span transposes downward.
771
+ * @returns The transposed note, octave-less if the source was.
772
+ * @example
773
+ * ```ts
774
+ * import { formatNote, transposeByInterval } from '@libraz/libcantus';
775
+ * formatNote(transposeByInterval('C4', 'A2')); // 'D#4'
776
+ * ```
777
+ * @category Pitch & Intervals
778
+ */
779
+ declare function transposeByInterval(given: NoteLike, named: IntervalLike): Note;
780
+ /**
781
+ * The spelled interval from one note to another.
782
+ *
783
+ * When both notes carry octaves, the interval reflects their full signed
784
+ * distance (so `C4 -> C5` is a perfect octave). When neither carries an octave
785
+ * the interval is measured within a single octave from `a` to `b`, normally
786
+ * ascending; a chromatic step down on one letter, such as `C -> Cb`, descends
787
+ * (`-A1`). Exactly one octave-bearing note has no defined answer and throws.
788
+ *
789
+ * @param a The lower/first note.
790
+ * @param b The upper/second note.
791
+ * @returns The diatonic number, quality, and semitone span.
792
+ * @throws If exactly one of the notes carries an octave.
793
+ * @example
794
+ * ```ts
795
+ * import { spelledInterval, parseNote } from '@libraz/libcantus';
796
+ * spelledInterval(parseNote('C4'), parseNote('G4'));
797
+ * // { number: 5, quality: 'P', semitones: 7, descending: false }
798
+ * ```
799
+ * @category Pitch & Intervals
800
+ */
801
+ declare function spelledInterval(a: Note, b: Note): SpelledInterval;
802
+
803
+ export { ARTICULATIONS as A, BudgetExceededError as B, toNoteData as C, toSpelledInterval as D, transposeByInterval as E, transposeNote as F, tryParseInterval as G, tryParseKeyName as H, tryParseNote as J, NoSolutionError as N, InvalidInputError as d, detectNoteNameSystem as l, diatonicLetterOf as m, formatKeyName as n, formatNote as o, intervalSemitones as p, isLibcantusError as q, midiToNote as r, naturalPitchClassOf as s, noteToMidi as t, noteToPitchClass as u, parseInterval as v, parseKeyName as w, parseNote as x, pitchClassOf as y, spelledInterval as z };
804
+ export type { IntervalData as I, KeyName as K, LibcantusError as L, ParseResult as P, SpelledInterval as S, Articulation as a, IntervalLike as b, IntervalQualityLabel as c, KeyScale as e, LibcantusErrorCode as f, Note as g, NoteEvent as h, NoteLike as i, NoteNameOptions as j, NoteNameSystem as k };