@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,493 @@
1
+ import { k as KeyVariant } from './coerce-Cr9AZsTY.js';
2
+
3
+ /**
4
+ * Build a 12-bit mode mask from a list of semitone offsets above the root.
5
+ *
6
+ * Bit 0 (the root) is always set, enforcing the `KeyScale` invariant that the
7
+ * root is a scale tone even when the offset list omits 0.
8
+ *
9
+ * @category Scales
10
+ */
11
+ declare function maskFromOffsets(offsets: readonly number[]): number;
12
+ /**
13
+ * Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}.
14
+ *
15
+ * @category Scales
16
+ */
17
+ declare const MAJOR_MASK = 2741;
18
+ /**
19
+ * Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}.
20
+ *
21
+ * @category Scales
22
+ */
23
+ declare const NATURAL_MINOR_MASK = 1453;
24
+ /**
25
+ * Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}.
26
+ *
27
+ * @category Scales
28
+ */
29
+ declare const HARMONIC_MINOR_MASK: number;
30
+ /**
31
+ * Ascending melodic minor: offsets {0,2,3,5,7,9,11}.
32
+ *
33
+ * @category Scales
34
+ */
35
+ declare const MELODIC_MINOR_MASK: number;
36
+ /**
37
+ * Dorian mode: offsets {0,2,3,5,7,9,10}.
38
+ *
39
+ * @category Scales
40
+ */
41
+ declare const DORIAN_MASK: number;
42
+ /**
43
+ * Phrygian mode: offsets {0,1,3,5,7,8,10}.
44
+ *
45
+ * @category Scales
46
+ */
47
+ declare const PHRYGIAN_MASK: number;
48
+ /**
49
+ * Lydian mode: offsets {0,2,4,6,7,9,11}.
50
+ *
51
+ * @category Scales
52
+ */
53
+ declare const LYDIAN_MASK: number;
54
+ /**
55
+ * Mixolydian mode: offsets {0,2,4,5,7,9,10}.
56
+ *
57
+ * @category Scales
58
+ */
59
+ declare const MIXOLYDIAN_MASK: number;
60
+ /**
61
+ * Locrian mode: offsets {0,1,3,5,6,8,10}.
62
+ *
63
+ * @category Scales
64
+ */
65
+ declare const LOCRIAN_MASK: number;
66
+ /**
67
+ * Major pentatonic: offsets {0,2,4,7,9}.
68
+ *
69
+ * @category Scales
70
+ */
71
+ declare const MAJOR_PENTATONIC_MASK: number;
72
+ /**
73
+ * Minor pentatonic: offsets {0,3,5,7,10}.
74
+ *
75
+ * @category Scales
76
+ */
77
+ declare const MINOR_PENTATONIC_MASK: number;
78
+ /**
79
+ * Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}.
80
+ *
81
+ * @category Scales
82
+ */
83
+ declare const BLUES_MASK: number;
84
+ /**
85
+ * Whole-tone scale: offsets {0,2,4,6,8,10}.
86
+ *
87
+ * @category Scales
88
+ */
89
+ declare const WHOLE_TONE_MASK: number;
90
+ /**
91
+ * Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}.
92
+ *
93
+ * @category Scales
94
+ */
95
+ declare const OCTATONIC_HALF_WHOLE_MASK: number;
96
+ /**
97
+ * Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}.
98
+ *
99
+ * @category Scales
100
+ */
101
+ declare const OCTATONIC_WHOLE_HALF_MASK: number;
102
+ /**
103
+ * Chromatic scale: all twelve pitch classes.
104
+ *
105
+ * @category Scales
106
+ */
107
+ declare const CHROMATIC_MASK = 4095;
108
+ /**
109
+ * Require a twelve-bit mode mask, and return it.
110
+ *
111
+ * A mask is read with bit operations, and those coerce: a `null` reads as the
112
+ * empty mask, an object as zero. Every answer taken from a mask is a musical
113
+ * claim — which form a key stands in, whether its signature is its own, which
114
+ * system it belongs to — so a value that is not a mask has to be refused rather
115
+ * than answered, and it is refused in one place so the answers cannot disagree
116
+ * about what a mask is.
117
+ *
118
+ * @param modeMask12 The value to check.
119
+ * @param name What the value is, for the error message.
120
+ * @returns The mask.
121
+ * @throws If it is not an integer in [1, {@link CHROMATIC_MASK}].
122
+ * @example
123
+ * ```ts
124
+ * import { assertModeMask, MAJOR_MASK } from '@libraz/libcantus';
125
+ * assertModeMask(MAJOR_MASK); // 2741
126
+ * ```
127
+ * @category Scales
128
+ */
129
+ declare function assertModeMask(modeMask12: number, name?: string): number;
130
+ /**
131
+ * Lydian dominant (melodic minor's fourth mode): offsets {0,2,4,6,7,9,10}.
132
+ *
133
+ * The scale over an unaltered dominant with a raised eleventh.
134
+ *
135
+ * @category Scales
136
+ */
137
+ declare const LYDIAN_DOMINANT_MASK: number;
138
+ /**
139
+ * Mixolydian b13, the aeolian dominant (melodic minor's fifth mode): offsets
140
+ * {0,2,4,5,7,8,10}.
141
+ *
142
+ * The scale over a dominant with a flat thirteenth.
143
+ *
144
+ * @category Scales
145
+ */
146
+ declare const MIXOLYDIAN_B13_MASK: number;
147
+ /**
148
+ * Locrian natural 2 (melodic minor's sixth mode): offsets {0,2,3,5,6,8,10}.
149
+ *
150
+ * The scale over a half-diminished chord used as a minor ii.
151
+ *
152
+ * @category Scales
153
+ */
154
+ declare const LOCRIAN_NATURAL2_MASK: number;
155
+ /**
156
+ * The altered scale, or superlocrian (melodic minor's seventh mode): offsets
157
+ * {0,1,3,4,6,8,10}.
158
+ *
159
+ * The scale over an altered dominant: every tension raised or lowered.
160
+ *
161
+ * @category Scales
162
+ */
163
+ declare const ALTERED_MASK: number;
164
+ /**
165
+ * Phrygian dominant (harmonic minor's fifth mode): offsets {0,1,4,5,7,8,10}.
166
+ *
167
+ * The scale over the dominant of a minor key, and the characteristic sound of
168
+ * the flamenco and maqam repertoires.
169
+ *
170
+ * @category Scales
171
+ */
172
+ declare const PHRYGIAN_DOMINANT_MASK: number;
173
+ /**
174
+ * Miyako-bushi (都節), the hemitonic pentatonic of Japanese urban art music —
175
+ * shamisen and koto song: offsets {0,1,5,7,8}.
176
+ *
177
+ * Two miyako-bushi tetrachords a fourth apart, in the terms of Koizumi's
178
+ * tetrachord theory: between the two nuclear tones of each tetrachord sits a
179
+ * note a semitone above the lower one.
180
+ *
181
+ * The mask fixes the pitch classes and nothing else: the repertoire's
182
+ * intonation is not twelve-tone equal temperament, and the scale is a pair of
183
+ * tetrachords around nuclear tones rather than a ladder of degrees above a
184
+ * tonic. Cents and non-12 temperaments are the tuning module's business.
185
+ *
186
+ * @category Scales
187
+ */
188
+ declare const MIYAKO_BUSHI_MASK: number;
189
+ /**
190
+ * Ritsu (律), the anhemitonic pentatonic of Japanese court music and Buddhist
191
+ * chant: offsets {0,2,5,7,9}.
192
+ *
193
+ * Two ritsu tetrachords a fourth apart: the middle note sits a whole tone above
194
+ * the lower nuclear tone. The result is the same five pitch classes as the
195
+ * major pentatonic a fourth above, which is why the mask alone cannot say which
196
+ * tradition is meant.
197
+ *
198
+ * @category Scales
199
+ */
200
+ declare const RITSU_MASK: number;
201
+ /**
202
+ * Ryūkyū (琉球), the pentatonic of Okinawan music: offsets {0,4,5,7,11}.
203
+ *
204
+ * Two ryūkyū tetrachords a fourth apart: the middle note sits a major third
205
+ * above the lower nuclear tone, which is what puts the two semitone steps under
206
+ * the fourth and the octave.
207
+ *
208
+ * @category Scales
209
+ */
210
+ declare const RYUKYU_MASK: number;
211
+ /**
212
+ * The heptatonic set with two augmented seconds: offsets {0,1,4,5,7,8,11}.
213
+ *
214
+ * Maqam Hijazkar in Arabic practice, thaat Bhairav in Hindustani practice, and
215
+ * the double harmonic major scale in English-language scale lists — one
216
+ * pitch-class set that three traditions arrived at separately and treat
217
+ * differently.
218
+ *
219
+ * @category Scales
220
+ */
221
+ declare const DOUBLE_HARMONIC_MASK: number;
222
+ /**
223
+ * Thaat Todi of Hindustani classical music — S r g M' P d N: offsets
224
+ * {0,1,3,6,7,8,11}.
225
+ *
226
+ * @category Scales
227
+ */
228
+ declare const TODI_MASK: number;
229
+ /**
230
+ * Thaat Marwa of Hindustani classical music — S r G M' P D N: offsets
231
+ * {0,1,4,6,7,9,11}.
232
+ *
233
+ * The thaat carries the fifth; raga Marwa itself leaves it out, which is the
234
+ * kind of distinction a pitch-class mask cannot make.
235
+ *
236
+ * @category Scales
237
+ */
238
+ declare const MARWA_MASK: number;
239
+ /**
240
+ * Thaat Purvi of Hindustani classical music — S r G M' P d N: offsets
241
+ * {0,1,4,6,7,8,11}.
242
+ *
243
+ * @category Scales
244
+ */
245
+ declare const PURVI_MASK: number;
246
+ /**
247
+ * Named scale masks addressable by {@link scaleByName}.
248
+ *
249
+ * These are the scales of Western common practice and of jazz, the vocabulary
250
+ * chord-scale theory is stated in. Scales belonging to traditions that chord
251
+ * function does not organise live in {@link WORLD_SCALES}, which
252
+ * {@link scaleByName} resolves just as readily; {@link scaleSystemOf} says
253
+ * which kind a name is.
254
+ *
255
+ * @category Scales
256
+ */
257
+ declare const NAMED_SCALES: Readonly<{
258
+ major: 2741;
259
+ ionian: 2741;
260
+ naturalMinor: 1453;
261
+ aeolian: 1453;
262
+ harmonicMinor: number;
263
+ melodicMinor: number;
264
+ dorian: number;
265
+ phrygian: number;
266
+ lydian: number;
267
+ mixolydian: number;
268
+ locrian: number;
269
+ lydianDominant: number;
270
+ mixolydianB13: number;
271
+ locrianNatural2: number;
272
+ altered: number;
273
+ phrygianDominant: number;
274
+ majorPentatonic: number;
275
+ minorPentatonic: number;
276
+ blues: number;
277
+ wholeTone: number;
278
+ octatonicHalfWhole: number;
279
+ octatonicWholeHalf: number;
280
+ chromatic: 4095;
281
+ }>;
282
+ /**
283
+ * The name of a built-in scale, as accepted by {@link scaleByName},
284
+ * {@link avoidNotes}, and {@link availableTensions}.
285
+ *
286
+ * @category Scales
287
+ */
288
+ type ScaleName = keyof typeof NAMED_SCALES;
289
+ /**
290
+ * Scale masks from traditions outside Western common practice, addressable by
291
+ * {@link scaleByName} exactly as {@link NAMED_SCALES} is.
292
+ *
293
+ * They are kept apart from {@link NAMED_SCALES} because chord-scale theory is a
294
+ * Western practice: a raga offered as the scale over an augmented major seventh
295
+ * would read as an answer while being a category error. Nothing else separates
296
+ * them — a `KeyScale` built from one of these masks behaves like any other.
297
+ *
298
+ * Three limits are worth stating plainly rather than leaving a caller to
299
+ * discover:
300
+ *
301
+ * - A twelve-bit mask can only hold what twelve-tone equal temperament can
302
+ * express. The maqamat that turn on half-flat degrees — Rast, Bayati, Saba,
303
+ * Sikah — are therefore absent rather than approximated, and the entries that
304
+ * are here are not tuned the way their traditions tune them. Cents, arbitrary
305
+ * equal divisions and just ratios live in the tuning module.
306
+ * - A thaat is the pitch material a raga draws on, not the raga: ascent and
307
+ * descent, the notes a phrase leans on, and the ornaments belong to the raga
308
+ * and have no place in a mask.
309
+ * - Several of these sets are the same pitch classes as a Western mode. The
310
+ * name is what carries the tradition, so pass the name, not the mask,
311
+ * wherever the tradition matters ({@link scaleSystemOf} reads both).
312
+ *
313
+ * The second limit is the general case: an entry is the pitch material a
314
+ * tradition names, never the modal system built on it. A maqam is assembled
315
+ * from ajnas that are transposed and exchanged as a phrase moves, and Koizumi's
316
+ * tetrachord theory describes the Japanese scales by the nuclear tones framing
317
+ * each tetrachord, so `miyakoBushi` and `minyo` differ by tetrachord type — a
318
+ * difference their pitch classes record without explaining. Reach for these
319
+ * entries when a pitch set is what is wanted.
320
+ *
321
+ * @category Scales
322
+ */
323
+ declare const WORLD_SCALES: Readonly<{
324
+ /** Miyako-bushi (都節), the hemitonic pentatonic of Japanese art music. */
325
+ miyakoBushi: number;
326
+ /** Ritsu (律), the anhemitonic pentatonic of Japanese court music and chant. */
327
+ ritsu: number;
328
+ /**
329
+ * Min'yō (民謡), the pentatonic of Japanese folk song, called inaka-bushi
330
+ * (田舎節) opposite miyako-bushi. The same five pitch classes as the minor
331
+ * pentatonic.
332
+ */
333
+ minyo: number;
334
+ /** Ryūkyū (琉球), the pentatonic of Okinawan music. */
335
+ ryukyu: number;
336
+ /** Maqam Ajam of Arabic practice; the same pitch classes as the major scale. */
337
+ ajam: 2741;
338
+ /**
339
+ * Maqam Nahawand of Arabic practice; the same pitch classes as the natural
340
+ * minor, though practice raises the seventh degree at a cadence.
341
+ */
342
+ nahawand: 1453;
343
+ /** Maqam Kurd of Arabic practice; the same pitch classes as the phrygian mode. */
344
+ kurd: number;
345
+ /**
346
+ * Maqam Hijaz of Arabic practice; the same pitch classes as the phrygian
347
+ * dominant. Played intonation stretches the augmented second beyond its
348
+ * tempered size, which is the sound the mask cannot carry.
349
+ */
350
+ hijaz: number;
351
+ /** Maqam Hijazkar of Arabic practice: Hijaz over Hijaz, with two augmented seconds. */
352
+ hijazkar: number;
353
+ /** Thaat Bilaval of Hindustani classical music; the same pitch classes as the major scale. */
354
+ bilaval: 2741;
355
+ /** Thaat Khamaj; the same pitch classes as the mixolydian mode. */
356
+ khamaj: number;
357
+ /** Thaat Kafi; the same pitch classes as the dorian mode. */
358
+ kafi: number;
359
+ /** Thaat Asavari; the same pitch classes as the natural minor. */
360
+ asavari: 1453;
361
+ /** Thaat Bhairavi; the same pitch classes as the phrygian mode. */
362
+ bhairavi: number;
363
+ /** Thaat Bhairav, with komal Re and komal Dha against a natural third and seventh. */
364
+ bhairav: number;
365
+ /** Thaat Kalyan; the same pitch classes as the lydian mode. */
366
+ kalyan: number;
367
+ /** Thaat Marwa, with komal Re and tivra Ma. */
368
+ marwa: number;
369
+ /** Thaat Purvi, Marwa's komal Dha counterpart. */
370
+ purvi: number;
371
+ /** Thaat Todi, with komal Re, komal Ga, komal Dha and tivra Ma. */
372
+ todi: number;
373
+ }>;
374
+ /**
375
+ * The name of a scale in {@link WORLD_SCALES}.
376
+ *
377
+ * @category Scales
378
+ */
379
+ type WorldScaleName = keyof typeof WORLD_SCALES;
380
+ /**
381
+ * Alternative names that resolve to a canonical scale name.
382
+ *
383
+ * A scale carrying several names gets one canonical entry and its other names
384
+ * here, so that two spellings of one tradition's scale cannot drift into two
385
+ * entries with two masks. Transliterations vary, and one pitch-class set is
386
+ * often named differently in different repertoires.
387
+ *
388
+ * @category Scales
389
+ */
390
+ declare const SCALE_ALIASES: Readonly<{
391
+ /** Inaka-bushi (田舎節), the name the in/yō pairing gives the min'yō scale. */
392
+ readonly inakaBushi: "minyo";
393
+ /** The Okinawan scale, the usual English name for the ryūkyū scale. */
394
+ readonly okinawan: "ryukyu";
395
+ /** Turkish spelling of Hijaz. */
396
+ readonly hicaz: "hijaz";
397
+ /** The English-language scale-list name for the Hijazkar/Bhairav set. */
398
+ readonly doubleHarmonic: "hijazkar";
399
+ /** Transliteration variant of Bilaval. */
400
+ readonly bilawal: "bilaval";
401
+ /** Transliteration variant of Marwa. */
402
+ readonly marva: "marwa";
403
+ /** Transliteration variant of Purvi. */
404
+ readonly poorvi: "purvi";
405
+ }>;
406
+ /**
407
+ * An alternative scale name that {@link resolveScaleName} maps to a canonical one.
408
+ *
409
+ * @category Scales
410
+ */
411
+ type ScaleAliasName = keyof typeof SCALE_ALIASES;
412
+ /**
413
+ * A scale name that completes to the built-in names but still accepts any
414
+ * string, so a caller with a name from configuration is not forced to cast.
415
+ *
416
+ * @category Scales
417
+ */
418
+ type ScaleNameInput = ScaleName | (string & {});
419
+ /**
420
+ * The canonical name a scale name stands for, or undefined when it names no
421
+ * built-in scale.
422
+ *
423
+ * A canonical name resolves to itself; an entry of {@link SCALE_ALIASES}
424
+ * resolves to the name it is an alias of. The lookup goes through
425
+ * `Object.hasOwn` for the same reason {@link namedScaleMask} does.
426
+ *
427
+ * @param name The scale name or alias.
428
+ * @returns The canonical name, or undefined for an unknown one.
429
+ * @example
430
+ * ```ts
431
+ * import { resolveScaleName } from '@libraz/libcantus';
432
+ * resolveScaleName('okinawan'); // 'ryukyu'
433
+ * resolveScaleName('dorian'); // 'dorian'
434
+ * ```
435
+ * @category Scales
436
+ */
437
+ declare function resolveScaleName(name: ScaleNameInput): ScaleName | WorldScaleName | undefined;
438
+ /**
439
+ * The mask of a named scale, or undefined when the name is not one.
440
+ *
441
+ * Names of {@link NAMED_SCALES}, of {@link WORLD_SCALES} and of
442
+ * {@link SCALE_ALIASES} all answer here, so a caller never has to know which
443
+ * register a scale is kept in.
444
+ *
445
+ * Looking the name up through this helper is what keeps `'constructor'` or
446
+ * `'toString'` from resolving to something inherited from `Object.prototype`
447
+ * and producing a scale whose mask is a function.
448
+ *
449
+ * @param name The scale name or alias.
450
+ * @returns The 12-bit mask, or undefined for an unknown name.
451
+ * @category Scales
452
+ */
453
+ declare function namedScaleMask(name: ScaleNameInput): number | undefined;
454
+ /**
455
+ * The mask of a named scale, rejecting an unknown name.
456
+ *
457
+ * Every public entry point that takes a scale name funnels through here, so a
458
+ * typo is reported the same way everywhere instead of being answered with an
459
+ * empty result that also means "this scale has none".
460
+ *
461
+ * @param name The scale name.
462
+ * @param label What the name is, for the error message.
463
+ * @returns The 12-bit mask.
464
+ * @throws If the name is not a built-in scale.
465
+ * @category Scales
466
+ */
467
+ declare function requireScaleMask(name: ScaleNameInput, label?: string): number;
468
+ /**
469
+ * The form a mask stands in, when it stands in one.
470
+ *
471
+ * A bare scale still names its form — a major mask is a major key whoever built
472
+ * it — so the form is read from the mask rather than defaulted away. Only a
473
+ * mask matching none of the four is modal.
474
+ */
475
+ declare function variantOfMask(modeMask12: number): KeyVariant;
476
+ /**
477
+ * Refuse a scale form the key's own mask does not hold.
478
+ *
479
+ * A key whose variant says `'harmonic'` over a major mask prints as a harmonic
480
+ * minor while comparing equal to plain C major, so a project file that carried
481
+ * the two apart is refused where the mismatch is still an argument. Kept beside
482
+ * the type it validates: the pairing of form and mask is written once, and
483
+ * every construction path reads that one.
484
+ *
485
+ * @param variant The form claimed for the key.
486
+ * @param modeMask12 The mask the key actually holds.
487
+ * @throws If the form is not one a key may stand in, or the mask does not hold it.
488
+ * @category Scales
489
+ */
490
+ declare function assertKeyVariant(variant: KeyVariant, modeMask12: number): void;
491
+
492
+ export { ALTERED_MASK as A, BLUES_MASK as B, CHROMATIC_MASK as C, DORIAN_MASK as D, resolveScaleName as E, variantOfMask as F, HARMONIC_MINOR_MASK as H, LOCRIAN_MASK as L, MAJOR_MASK as M, NAMED_SCALES as N, OCTATONIC_HALF_WHOLE_MASK as O, PHRYGIAN_DOMINANT_MASK as P, RITSU_MASK as R, SCALE_ALIASES as S, TODI_MASK as T, WHOLE_TONE_MASK as W, DOUBLE_HARMONIC_MASK as a, LOCRIAN_NATURAL2_MASK as b, LYDIAN_DOMINANT_MASK as c, LYDIAN_MASK as d, MAJOR_PENTATONIC_MASK as e, MARWA_MASK as f, MELODIC_MINOR_MASK as g, MINOR_PENTATONIC_MASK as h, MIXOLYDIAN_B13_MASK as i, MIXOLYDIAN_MASK as j, MIYAKO_BUSHI_MASK as k, NATURAL_MINOR_MASK as l, OCTATONIC_WHOLE_HALF_MASK as m, PHRYGIAN_MASK as n, PURVI_MASK as o, RYUKYU_MASK as p, WORLD_SCALES as t, assertKeyVariant as v, assertModeMask as w, maskFromOffsets as x, namedScaleMask as y, requireScaleMask as z };
493
+ export type { ScaleAliasName as q, ScaleName as r, ScaleNameInput as s, WorldScaleName as u };