@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,1337 @@
1
+ import { e as KeyScale, g as Note, i as NoteLike } from './index-C9MYbuKS.js';
2
+
3
+ /**
4
+ * The vocabulary a key is described in.
5
+ *
6
+ * Kept in a module of its own, below the masks that define the scale forms, the
7
+ * name reader that produces a key from text, and the coercion that accepts one
8
+ * from a caller. All three name these types and none of them can be the others'
9
+ * home without importing one back.
10
+ */
11
+ /**
12
+ * Which scale form a key stands in.
13
+ *
14
+ * `'modal'` is the honest answer for a key standing in none of the four, and it
15
+ * is an answer rather than an absence.
16
+ *
17
+ * @category Scales
18
+ */
19
+ type KeyVariant = 'major' | 'natural' | 'harmonic' | 'melodic' | 'modal';
20
+ /**
21
+ * The complete identity of a key: what it sounds, how it is written, and which
22
+ * scale form it stands in.
23
+ *
24
+ * What {@link resolveKey} hands back, and the shape a key is passed on in. Every
25
+ * field is present: a key that reaches here has been read, so there is nothing
26
+ * left undecided about it, and a reader never has to ask whether a missing
27
+ * field means `'modal'` or means nobody looked.
28
+ *
29
+ * @category Scales
30
+ */
31
+ /**
32
+ * A key/scale with the spelling it is conventionally written in beside it.
33
+ *
34
+ * What the key builders hand back. It is a {@link KeyScale} — every reader that
35
+ * wants only the pitch classes takes it unchanged — and it carries the tonic
36
+ * those pitch classes are conventionally written on, so it also satisfies the
37
+ * entry points whose answer depends on how the key is written.
38
+ *
39
+ * Carrying the spelling here is what lets those entry points refuse a bare
40
+ * `KeyScale` without refusing the library's own builders. A bare scale reaching
41
+ * one of them has had a spelling and lost it, which is the defect; a built key
42
+ * never lost one.
43
+ *
44
+ * @category Scales
45
+ */
46
+ type SpelledKeyScale = KeyScale & {
47
+ /** The tonic the key is conventionally written on. */
48
+ tonic: Note;
49
+ /** The scale form the mask stands in. */
50
+ variant: KeyVariant;
51
+ };
52
+ /**
53
+ * A key read into the three things every reader of one needs: the pitch
54
+ * classes it is built from, the spelled tonic its letter names are anchored on,
55
+ * and the scale form it stands in.
56
+ *
57
+ * What a key-shaped argument becomes once it has been read, whatever form the
58
+ * caller held it in — a name, a scale, a `Key`. Carrying the tonic beside the
59
+ * scale is what keeps an A flat minor an A flat minor rather than the G sharp
60
+ * minor its pitch classes alone would be spelled back as.
61
+ *
62
+ * @category Scales
63
+ */
64
+ type ResolvedKey = {
65
+ /** The pitch classes the key is built from. */
66
+ readonly scale: KeyScale;
67
+ /** The spelled tonic every letter name derived from this key is anchored on. */
68
+ readonly tonic: Note;
69
+ /** The scale form the key stands in. */
70
+ readonly variant: KeyVariant;
71
+ };
72
+
73
+ /**
74
+ * Anything that names a key: a key name, a plain {@link KeyScale}, the plain
75
+ * data a key serializes to, or a value that serializes to one such as the `Key`
76
+ * class.
77
+ *
78
+ * The plain-data form is here because a project file holds a key that way, and
79
+ * reading one back has to be the same call as passing the class it came from.
80
+ *
81
+ * Deliberately wider than what a resolver hands back: a caller may hand in a
82
+ * bare scale, or data written before the spelling travelled with it, and the
83
+ * resolver fills in what is missing rather than refusing it. Narrowing this to
84
+ * the resolved shape would make the acceptance of every entry point shrink the
85
+ * day the resolved shape gained a field.
86
+ *
87
+ * A scale is accepted with the spelling and the form written beside it as well
88
+ * as without them, because a key region carries its key that way — asked
89
+ * positional questions wherever a plain scale would be. The resolver reads them
90
+ * when they are there, and this says so: a shape a resolver reads and a type
91
+ * denies is one refactoring away from being dropped silently.
92
+ *
93
+ * @category Scales
94
+ */
95
+ type KeyLike = string | (KeyScale & {
96
+ /** The spelled tonic the key is written with, when it travels beside it. */
97
+ tonic?: Note;
98
+ /** The scale form the key stands in, when it travels beside it. */
99
+ variant?: KeyVariant;
100
+ }) | {
101
+ /** The scale this key data denotes. */
102
+ scale: KeyScale;
103
+ /** The spelled tonic the key is written with, when the caller named one. */
104
+ tonic?: Note;
105
+ /** The scale form the key was read under, when it was read under one. */
106
+ variant?: KeyVariant;
107
+ } | {
108
+ /** The key data this value stands for, carrying everything it knows. */
109
+ toJSON(): {
110
+ scale: KeyScale;
111
+ tonic?: Note;
112
+ variant?: KeyVariant;
113
+ };
114
+ };
115
+ /**
116
+ * A key that says how it is written, for the entry points whose answer depends
117
+ * on it.
118
+ *
119
+ * The shapes {@link KeyLike} accepts, minus the one that cannot carry a
120
+ * spelling: a bare {@link KeyScale}. An A flat minor and a G sharp minor are one
121
+ * set of pitch classes and two keys, so an entry point whose answer differs
122
+ * between them cannot be handed the shape that does not distinguish them and
123
+ * still be right. Declaring this makes that a compile error rather than a
124
+ * defect found later — and `Key`, `ResolvedKey`, a key name and stored key data
125
+ * all satisfy it, so the narrowing costs a caller nothing it was doing
126
+ * correctly.
127
+ *
128
+ * Which entry points declare this is measured rather than chosen: an entry point
129
+ * belongs here exactly when varying its key argument alone — between the two
130
+ * spellings of one sound — changes its answer. A scale a caller genuinely wants
131
+ * to hand in is spelled first, at the place it happens, which is the same rule
132
+ * the reduction in the other direction already follows.
133
+ *
134
+ * @category Scales
135
+ */
136
+ type SpelledKeyLike = string | (KeyScale & {
137
+ /** The spelled tonic the key is written with. Required: it is the point. */
138
+ tonic: Note;
139
+ /** The scale form the key stands in, when it travels beside it. */
140
+ variant?: KeyVariant;
141
+ }) | {
142
+ /** The scale this key data denotes. */
143
+ scale: KeyScale;
144
+ /** The spelled tonic the key is written with, when the caller named one. */
145
+ tonic?: Note;
146
+ /** The scale form the key was read under, when it was read under one. */
147
+ variant?: KeyVariant;
148
+ } | {
149
+ /** The key data this value stands for, carrying everything it knows. */
150
+ toJSON(): {
151
+ scale: KeyScale;
152
+ tonic?: Note;
153
+ variant?: KeyVariant;
154
+ };
155
+ };
156
+ /**
157
+ * Resolve any key-shaped value to a plain {@link KeyScale}.
158
+ *
159
+ * The counterpart of {@link toSpelledInterval} for keys: an entry point takes
160
+ * whatever form the caller has — the name a key field holds, the scale the
161
+ * theory module returns, or a `Key` instance — and gets one shape back. An
162
+ * instance is accepted through its `toJSON` method rather than by its type, so
163
+ * the layers below the model can read a class without importing it.
164
+ *
165
+ * A name is read by the one reader {@link resolveKey} and `Key.parse` also use,
166
+ * so every entry point that takes a key accepts exactly the same names: a mode
167
+ * word in every notation system that reader knows, and a built-in scale's own
168
+ * word — `'D dorian'`, `'D harmonic minor'` — in English.
169
+ * The spelling the name carries is dropped here along with the scale form,
170
+ * which is what {@link resolveKey} is for.
171
+ *
172
+ * @param value A key name, a plain key/scale, or a value whose `toJSON`
173
+ * returns data carrying one.
174
+ * @returns The validated key/scale, with its root reduced to a pitch class.
175
+ * @throws If the value names no key, or its mode mask is out of range or
176
+ * excludes its own root.
177
+ * @example
178
+ * ```ts
179
+ * import { toKeyScale } from '@libraz/libcantus';
180
+ * toKeyScale('C major').rootPc; // 0
181
+ * toKeyScale('A minor').rootPc; // 9
182
+ * ```
183
+ * @category Scales
184
+ */
185
+ declare function toKeyScale(value: KeyLike): KeyScale;
186
+
187
+ /**
188
+ * How keys stand to one another: the relative, parallel, dominant and
189
+ * subdominant keys, the enharmonic respelling of a key, and the relation that
190
+ * holds between two given keys.
191
+ *
192
+ * Every relation but {@link parallelKeyOf} is computed in fifths space, on top
193
+ * of {@link keySignatureFifths} and {@link keyFromFifths}. Stepping around the
194
+ * circle of fifths and reading the tonic back off it is what keeps the spelling
195
+ * right: the relative of Db major comes out as Bb minor, not A# minor.
196
+ *
197
+ * A relation always returns a plain major or minor key, because those are the
198
+ * only keys these relations name; {@link enharmonicKeyOf} is the exception that
199
+ * proves it, since a respelling is the same key rather than another one and so
200
+ * keeps the mask it was handed. A key that is not a plain major or minor —
201
+ * a church mode, harmonic minor, a pentatonic, an octatonic — is read through
202
+ * the mode its third names, and the fifths are counted from where its tonic
203
+ * stands on the circle rather than from the key's own signature: a mode's
204
+ * signature carries its own offset (D dorian is two fifths flatter than D
205
+ * major), which {@link keyFromFifths} does not know how to give back.
206
+ * {@link parallelKeyOf} travels no fifths at all, so it keeps the tonic
207
+ * spelling it was given.
208
+ */
209
+
210
+ /**
211
+ * A key paired with the spelled tonic that anchors its letter names.
212
+ *
213
+ * The tonic carries no octave: a key is rooted on a pitch class, and its
214
+ * spelling is what decides whether the key is written Db major or C# major.
215
+ *
216
+ * @example
217
+ * ```ts
218
+ * import type { ResolvedKey } from '@libraz/libcantus';
219
+ * import { formatNote, majorKey, spelledKeyOf } from '@libraz/libcantus';
220
+ * const dbMajor: ResolvedKey = spelledKeyOf(majorKey(1));
221
+ * formatNote(dbMajor.tonic); // 'Db'
222
+ * ```
223
+ * @category Scales
224
+ */
225
+ /**
226
+ * How one key stands to another, as reported by {@link keyRelationBetween} and
227
+ * tagged onto every entry of {@link relatedKeysOf}.
228
+ *
229
+ * @example
230
+ * ```ts
231
+ * import type { KeyRelation } from '@libraz/libcantus';
232
+ * const relation: KeyRelation = 'relative'; // C major -> A minor
233
+ * ```
234
+ * @category Scales
235
+ */
236
+ type KeyRelation = 'same' | 'enharmonic' | 'relative' | 'parallel' | 'dominant' | 'subdominant' | 'relativeOfDominant' | 'relativeOfSubdominant';
237
+ /**
238
+ * Spell a key's tonic the conventional way: the letter and accidental the key
239
+ * is written with, paired with the key exactly as given.
240
+ *
241
+ * The candidates are the tonics keys are actually written on — everything from
242
+ * Cb to A#, which names each pitch class once or twice (C, but Db and C#) — and
243
+ * which of them names the key depends on whether the key has a signature of its
244
+ * own. A major or minor key, a church mode, and the harmonic and melodic minor
245
+ * are spelled on the tonic their signature is written on: pitch class 1 in
246
+ * major is Db, five flats, rather than C#, seven sharps; pitch class 8 in minor
247
+ * is G#, five sharps, rather than Ab, seven flats; and G# harmonic minor writes
248
+ * its raised seventh F## as an accidental over that signature rather than
249
+ * respelling the key. Where two signatures are equally long — pitch class 6 in
250
+ * major is F# at +6 and Gb at -6 — the flat side is taken.
251
+ *
252
+ * Every other scale only borrows the signature of its parallel major or minor,
253
+ * so nothing follows from it and the scale is spelled on the tonic it reads
254
+ * best from: the fewest double accidentals first, then the fewest accidentals
255
+ * altogether, and only then the shorter signature. That is why pitch class 1
256
+ * altered is C# — C# D E F G A B — rather than Db, which would have to write
257
+ * four double flats to say the same thing, and why pitch class 8 minor
258
+ * pentatonic is G# B C# D# F# rather than Ab B Db Eb Gb, which reads its third
259
+ * as an augmented second.
260
+ *
261
+ * The mask's third picks the mode the signature is measured in — a minor third
262
+ * and no major third reads as minor, anything else as major — and the key is
263
+ * returned unchanged, so a scale keeps its own mask and only borrows a tonic
264
+ * spelling. A caller that has a tonic spelling of its own always keeps it: this
265
+ * only answers for a key that arrives as a bare pitch class.
266
+ *
267
+ * Every 12-bit mask and every integer root is answered — a root outside [0, 11]
268
+ * is reduced first, and a mask with no third at all counts as major.
269
+ *
270
+ * The key is paired with the answer exactly as it was handed in, root and mask
271
+ * untouched, so this takes a plain key/scale rather than the wider forms the
272
+ * relations below accept: a coerced key could not be given back verbatim.
273
+ *
274
+ * @param key The key/scale to spell.
275
+ * @returns The conventional tonic spelling, paired with `key` verbatim.
276
+ * @example
277
+ * ```ts
278
+ * import { formatNote, majorKey, scaleByName, spelledKeyOf } from '@libraz/libcantus';
279
+ * formatNote(spelledKeyOf(majorKey(1)).tonic); // 'Db'
280
+ * formatNote(spelledKeyOf(scaleByName('harmonicMinor', 8)).tonic); // 'G#'
281
+ * formatNote(spelledKeyOf(scaleByName('altered', 1)).tonic); // 'C#'
282
+ * ```
283
+ * @category Scales
284
+ */
285
+ declare function spelledKeyOf(key: KeyScale): ResolvedKey;
286
+ /**
287
+ * The relative key: for a plain major or minor key, the same key signature read
288
+ * in the other mode.
289
+ *
290
+ * C major and A minor share a signature, and so are each other's relative; the
291
+ * relation is its own inverse for a plain major or minor key. Because the new
292
+ * tonic is read off the circle of fifths rather than transposed by semitones,
293
+ * the relative of Db major is Bb minor and not its enharmonic A# minor.
294
+ *
295
+ * A key that is not a plain major or minor is read through the mode its third
296
+ * names and stepped from where its tonic stands on the circle, the origin every
297
+ * relation here shares: the relative of D dorian is F major, the relative of the
298
+ * D minor its third names. The shared-signature reading does not carry over to
299
+ * those — D dorian is written with no accidentals and F major with one — and the
300
+ * modes have no relative of their own for it to be measured against.
301
+ *
302
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
303
+ * `Note`.
304
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
305
+ * decides which mode the relative is in.
306
+ * @returns The relative key and the tonic spelling it is written with.
307
+ * @throws If the tonic or the mask is malformed, or if the resulting signature
308
+ * falls outside [-12, 12] fifths.
309
+ * @example
310
+ * ```ts
311
+ * import { formatNote, majorKey, parseNote, relativeKeyOf } from '@libraz/libcantus';
312
+ * formatNote(relativeKeyOf(parseNote('C'), majorKey(0)).tonic); // 'A'
313
+ * formatNote(relativeKeyOf('Db', majorKey(1)).tonic); // 'Bb'
314
+ * ```
315
+ * @category Scales
316
+ */
317
+ declare function relativeKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey;
318
+ /**
319
+ * The parallel key: the other mode on the same tonic.
320
+ *
321
+ * The tonic keeps the spelling it was given — the parallel minor of C major is
322
+ * C minor, never B# minor — which is why this is the one relation here that
323
+ * does not travel the circle of fifths.
324
+ *
325
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
326
+ * `Note`; its letter and alteration are kept.
327
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
328
+ * decides which mode the parallel is in.
329
+ * @returns The parallel key on the same tonic.
330
+ * @throws If the tonic or the mask is malformed.
331
+ * @example
332
+ * ```ts
333
+ * import { formatNote, majorKey, parallelKeyOf, parseNote } from '@libraz/libcantus';
334
+ * const parallel = parallelKeyOf(parseNote('C'), majorKey(0));
335
+ * formatNote(parallel.tonic); // 'C'
336
+ * ```
337
+ * @category Scales
338
+ */
339
+ declare function parallelKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey;
340
+ /**
341
+ * The dominant key: the key a fifth above, in the mode this key's third names.
342
+ *
343
+ * The fifth is measured from the tonic, so a key that is not a plain major or
344
+ * minor answers with the same move: the dominant of G mixolydian is D major and
345
+ * the dominant of D dorian is A minor.
346
+ *
347
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
348
+ * `Note`.
349
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
350
+ * decides the mode of the result.
351
+ * @returns The key a fifth above, in the mode this key's third names.
352
+ * @throws If the tonic or the mask is malformed, or if the resulting signature
353
+ * falls outside [-12, 12] fifths — the dominant of a key already at +12.
354
+ * @example
355
+ * ```ts
356
+ * import { dominantKeyOf, formatNote, majorKey, parseNote } from '@libraz/libcantus';
357
+ * formatNote(dominantKeyOf(parseNote('C'), majorKey(0)).tonic); // 'G'
358
+ * ```
359
+ * @category Scales
360
+ */
361
+ declare function dominantKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey;
362
+ /**
363
+ * The subdominant key: the key a fifth below, in the mode this key's third
364
+ * names, and the exact inverse of {@link dominantKeyOf} on the tonic spelling.
365
+ *
366
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
367
+ * `Note`.
368
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
369
+ * decides the mode of the result.
370
+ * @returns The key a fifth below, in the mode this key's third names.
371
+ * @throws If the tonic or the mask is malformed, or if the resulting signature
372
+ * falls outside [-12, 12] fifths — the subdominant of a key already at -12.
373
+ * @example
374
+ * ```ts
375
+ * import { formatNote, majorKey, parseNote, subdominantKeyOf } from '@libraz/libcantus';
376
+ * formatNote(subdominantKeyOf(parseNote('C'), majorKey(0)).tonic); // 'F'
377
+ * ```
378
+ * @category Scales
379
+ */
380
+ declare function subdominantKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey;
381
+ /**
382
+ * The same sounding key written the other way round the circle of fifths, or
383
+ * null when it has no second spelling.
384
+ *
385
+ * Twelve fifths is one enharmonic turn of the circle, so a tonic's alternative
386
+ * spelling sits at its own position ±12: Db (-5) is also C# (+7). It is offered
387
+ * only when the key is actually written there, by the same test
388
+ * {@link spelledKeyOf} spells with. That is why C major is alone while Db major
389
+ * and F# major each answer with their twin: Eb major's twin would be D# major
390
+ * and its nine sharps, and pitch class 3 altered is written D# but never Eb,
391
+ * which would need two double flats to say the same thing.
392
+ *
393
+ * The answer is therefore always a spelling the key is written on, which makes
394
+ * the relation its own inverse for such a key. A key spelled some other way —
395
+ * a tonic a transposition drove out to Ebb, say — still names its written twin,
396
+ * so this is also the way back from a spelling no one writes.
397
+ *
398
+ * The relation respells rather than moves, so the mask is kept: the other
399
+ * spelling of C# lydian is Db lydian, and its root pitch class is the one it
400
+ * was handed.
401
+ *
402
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
403
+ * `Note`.
404
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
405
+ * decides the mode the tonic is read in, and is carried into the result.
406
+ * @returns The other spelling of the key, or null when it is not written.
407
+ * @throws If the tonic or the mask is malformed.
408
+ * @example
409
+ * ```ts
410
+ * import { enharmonicKeyOf, formatNote, majorKey, parseNote } from '@libraz/libcantus';
411
+ * const other = enharmonicKeyOf(parseNote('Db'), majorKey(1));
412
+ * other === null ? 'none' : formatNote(other.tonic); // 'C#'
413
+ * enharmonicKeyOf('C', majorKey(0)); // null
414
+ * ```
415
+ * @category Scales
416
+ */
417
+ declare function enharmonicKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey | null;
418
+ /**
419
+ * The six closely related keys of a key, each tagged with its relation.
420
+ *
421
+ * These are the keys the German and Japanese teaching tradition counts as a
422
+ * key's near relations: the relative and parallel keys, the dominant and the
423
+ * subdominant, and the relatives of those two. For C major they are A minor,
424
+ * C minor, G major, F major, E minor and D minor, in that order. For a plain
425
+ * major or minor key five of them are written within one accidental of the key's
426
+ * own signature — the relative shares it exactly and the other four stand one
427
+ * away; the parallel key does not — C minor is three flats away from C major —
428
+ * and belongs to the set for the tonic it shares rather than for the signature
429
+ * it carries.
430
+ *
431
+ * A key that is not a plain major or minor is read through the mode its third
432
+ * names, so its relations are walked from where its tonic stands on the circle
433
+ * rather than from its own signature, and the accidental counts above do not
434
+ * describe them: the relative of D dorian is F major, one flat against dorian's
435
+ * none.
436
+ *
437
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
438
+ * `Note`.
439
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`.
440
+ * @returns The six related keys, in relation order, each with its tonic
441
+ * spelling and its `relation` tag.
442
+ * @throws If the tonic or the mask is malformed, or if a neighbouring signature
443
+ * falls outside [-12, 12] fifths.
444
+ * @example
445
+ * ```ts
446
+ * import { majorKey, parseNote, relatedKeysOf } from '@libraz/libcantus';
447
+ * relatedKeysOf(parseNote('C'), majorKey(0)).map((related) => related.relation);
448
+ * // ['relative', 'parallel', 'dominant', 'subdominant', 'relativeOfDominant', 'relativeOfSubdominant']
449
+ * ```
450
+ * @category Scales
451
+ */
452
+ declare function relatedKeysOf(tonic: NoteLike, key: KeyLike): (ResolvedKey & {
453
+ relation: KeyRelation;
454
+ })[];
455
+ /**
456
+ * How the second key stands to the first, or null when they are not related.
457
+ *
458
+ * The relations are tested in a fixed order — identity, enharmonic spelling,
459
+ * then the six closely related keys in the order {@link relatedKeysOf} lists
460
+ * them — and the first match is reported. Only the identity test looks at the
461
+ * tonic spelling; every other test compares root pitch class and mode, so
462
+ * C# minor and Db minor both read as the relative of E major.
463
+ *
464
+ * Both keys are read through the mode their third names, exactly as
465
+ * {@link relatedKeysOf} reads the key it is given, so A harmonic minor stands
466
+ * to C major as A minor does whichever of the two is asked about. That is what
467
+ * makes the answer symmetric: if one key's related keys name the other, the
468
+ * relation between them is reported from either side.
469
+ *
470
+ * @param a The key the relation is measured from.
471
+ * @param b The key the relation is measured to.
472
+ * @returns The relation, or null when `b` is none of `a`'s related keys.
473
+ * @throws If either key is malformed, or if a neighbouring signature of `a`
474
+ * falls outside [-12, 12] fifths.
475
+ * @example
476
+ * ```ts
477
+ * import { keyRelationBetween, majorKey, minorKey, spelledKeyOf } from '@libraz/libcantus';
478
+ * const cMajor = spelledKeyOf(majorKey(0));
479
+ * keyRelationBetween(cMajor, spelledKeyOf(minorKey(9))); // 'relative'
480
+ * keyRelationBetween(cMajor, spelledKeyOf(minorKey(3))); // null
481
+ * ```
482
+ * @category Scales
483
+ */
484
+ declare function keyRelationBetween(a: ResolvedKey, b: ResolvedKey): KeyRelation | null;
485
+
486
+ /**
487
+ * The structured reading of a chord: what it is built from, not what it is
488
+ * called.
489
+ *
490
+ * A quality name is a closed vocabulary and a lead sheet's harmony is not. A
491
+ * chart writes a *set* of alterations over a base — `maj7#11`, `7b9#11`,
492
+ * `sus4(add9)` — so an enumeration of names can never be complete, and every
493
+ * name added to one is a name missing from its neighbours. A {@link ChordSpec}
494
+ * names the parts instead: a base triad, an optional seventh, altered, added
495
+ * and omitted degrees. A combination nothing names still has exact intervals,
496
+ * an exact pitch-class set, and a symbol that reads back as itself.
497
+ *
498
+ * Each {@link ChordQuality} is an alias for one spec, so the two directions
499
+ * cannot drift: a named chord's interval template is derived from its spec
500
+ * rather than listed beside it.
501
+ */
502
+ /**
503
+ * Chord quality identifiers understood by the chord builder.
504
+ *
505
+ * Each name is an alias for one {@link ChordSpec}. The union is closed, so it
506
+ * names the chords a chart writes most often rather than every chord that can
507
+ * be written; build the rest from a spec.
508
+ *
509
+ * @category Chords
510
+ */
511
+ type ChordQuality = 'maj' | 'min' | 'dim' | 'aug' | 'maj7' | 'min7' | 'dom7' | 'dim7' | 'm7b5' | 'minMaj7' | 'minMaj9' | 'minMaj11' | 'minMaj13' | 'aug7' | 'augMaj7' | 'majb5' | '6' | 'min6' | '6/9' | 'sus2' | 'sus4' | 'add9' | 'add11' | 'maj9' | 'min9' | 'dom9' | '7b9' | '7#9' | '7#11' | '7b13' | '11' | '13' | '5' | '7sus4' | '7b5' | '7alt' | '13b9' | 'maj13' | 'maj7#11' | 'min11' | 'min13' | 'minAdd9' | 'min6/9';
512
+ /**
513
+ * The triad (or dyad) a chord is built on, before any seventh or tension.
514
+ *
515
+ * `sus2` and `sus4` replace the third rather than sitting beside it, and
516
+ * `power` is the bare root and fifth, so the base says which tones the chord
517
+ * has before anything is added to them.
518
+ *
519
+ * @category Chords
520
+ */
521
+ type ChordBase = 'maj' | 'min' | 'dim' | 'aug' | 'sus2' | 'sus4' | 'power';
522
+ /**
523
+ * The seventh stacked over a base: major, minor, or diminished.
524
+ *
525
+ * @category Chords
526
+ */
527
+ type ChordSeventh = 'maj7' | 'min7' | 'dim7';
528
+ /**
529
+ * A chord degree that can be raised or lowered: the fifth and the tensions.
530
+ *
531
+ * @category Chords
532
+ */
533
+ type AlteredDegree = 5 | 9 | 11 | 13;
534
+ /**
535
+ * One altered degree: which one, and by how much.
536
+ *
537
+ * `alter: 0` is not redundant — it says the degree is *present* and unaltered,
538
+ * which is what the natural ninth of a thirteenth chord is.
539
+ *
540
+ * @category Chords
541
+ */
542
+ type Alteration = {
543
+ degree: AlteredDegree;
544
+ alter: -1 | 0 | 1;
545
+ };
546
+ /**
547
+ * A chord as its parts: base, seventh, alterations, additions and omissions.
548
+ *
549
+ * The library's structural chord model. `alterations` are tensions over a
550
+ * seventh chord; `additions` are degrees added without one (`add9`, and the
551
+ * sixth of a sixth chord); `omissions` are degrees the chord leaves out (the
552
+ * third of an eleventh chord, the fifth of a shell voicing) named by chord
553
+ * degree, so `omissions: [5]` is a fifth-less chord.
554
+ *
555
+ * @category Chords
556
+ */
557
+ type ChordSpec = {
558
+ rootPc: number;
559
+ base: ChordBase;
560
+ seventh?: ChordSeventh;
561
+ alterations: Alteration[];
562
+ additions: number[];
563
+ omissions: number[];
564
+ bassPc?: number;
565
+ };
566
+ /**
567
+ * The semitone offsets above the root a spec sounds, ascending.
568
+ *
569
+ * The library's single derivation of chord tones: a name contributes nothing
570
+ * here, so a combination of alterations no name covers yields its intervals the
571
+ * same way a `maj7` does.
572
+ *
573
+ * @param spec The chord spec.
574
+ * @returns Semitone offsets above the root, ascending and deduplicated.
575
+ * @throws If any part of the spec is not one the model defines
576
+ * ({@link InvalidInputError}), exactly as {@link chordFromSpec} rejects it.
577
+ *
578
+ * @example
579
+ * ```ts
580
+ * import { chordSpecIntervals } from '@libraz/libcantus';
581
+ * chordSpecIntervals({
582
+ * rootPc: 0,
583
+ * base: 'maj',
584
+ * seventh: 'min7',
585
+ * alterations: [{ degree: 9, alter: -1 }, { degree: 11, alter: 1 }],
586
+ * additions: [],
587
+ * omissions: [],
588
+ * });
589
+ * // [0, 4, 7, 10, 13, 18] — the C7(b9,#11) no quality name covers
590
+ * ```
591
+ *
592
+ * @category Chords
593
+ */
594
+ declare function chordSpecIntervals(spec: ChordSpec): number[];
595
+ /**
596
+ * The quality name a spec is reported under.
597
+ *
598
+ * A spec no name covers still has to answer, because `quality` is a required
599
+ * field of every {@link Chord} and of the records that travel with one. The
600
+ * answer is the *nearest* name: the largest named chord whose every tone this
601
+ * spec also sounds, and failing that the name of its base. Nothing is lost by
602
+ * it — the spec and the interval template still carry the alterations, and a
603
+ * symbol is written from those rather than from this name.
604
+ *
605
+ * @param spec The chord spec.
606
+ * @returns The name that fits the spec exactly, or the nearest one that fits
607
+ * inside it.
608
+ * @throws If any part of the spec is not one the model defines
609
+ * ({@link InvalidInputError}), exactly as {@link chordFromSpec} rejects it.
610
+ *
611
+ * @example
612
+ * ```ts
613
+ * import { chordSpecQuality, parseChordSymbol } from '@libraz/libcantus';
614
+ * parseChordSymbol('C7(b9,#11)').quality; // '7b9' — the nearest name
615
+ * chordSpecQuality({ rootPc: 0, base: 'maj', seventh: 'min7', alterations: [],
616
+ * additions: [], omissions: [] }); // 'dom7'
617
+ * ```
618
+ *
619
+ * @category Chords
620
+ */
621
+ declare function chordSpecQuality(spec: ChordSpec): ChordQuality;
622
+
623
+ /**
624
+ * The basic role a chord tone plays: the degrees a chord's own template names.
625
+ *
626
+ * The shared vocabulary behind {@link chordToneRole}, the harmony layer's
627
+ * `HarmonyRole`, and the voice analyser's labels, so the three cannot drift.
628
+ *
629
+ * @category Chords
630
+ */
631
+ type ChordToneRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
632
+ /**
633
+ * A bare spelled pitch used as an enharmonic hint: a diatonic letter
634
+ * (0..6 = C..B) plus a chromatic alteration (-2 double-flat .. +2 double-sharp).
635
+ * Mirrors the letter/alter half of the pitch module's `Note` without an octave.
636
+ *
637
+ * @category Chords
638
+ */
639
+ type PitchSpelling = {
640
+ letter: number;
641
+ alter: number;
642
+ };
643
+ /**
644
+ * A chord expressed as a root pitch class plus semitone offsets.
645
+ *
646
+ * `intervals` is what the chord sounds and `quality` is what it is called. The
647
+ * two are not equally expressive: a chart writes any set of alterations over a
648
+ * base, while {@link ChordQuality} is a closed list of names, so `quality` is a
649
+ * *derived* label — the name that fits the chord exactly, or else the nearest
650
+ * name inside it (see {@link chordSpecQuality}). Read the structure with
651
+ * {@link chordSpecOf} rather than the name when the alterations matter; that is
652
+ * also what {@link formatChordSymbol} does, so a chord no name covers still
653
+ * writes itself out in full.
654
+ *
655
+ * `rootSpelling`/`bassSpelling` are optional enharmonic hints recorded by
656
+ * parsers (e.g. `parseChordSymbol('Bb7')`) so formatters can reproduce the
657
+ * original spelling instead of defaulting to sharps. Consumers may ignore
658
+ * them; a hint is only trusted when its pitch class still matches the
659
+ * corresponding `rootPc`/`bassPc`.
660
+ *
661
+ * `toneSpellings` is the same kind of hint for the tones themselves, one
662
+ * spelling per entry in `intervals`. It exists for the chords whose letters do
663
+ * not follow from stacking thirds: an augmented sixth is ten semitones like a
664
+ * minor seventh but is five letters above its root rather than six, and no
665
+ * {@link ChordQuality} can say so. Builders that know better attach it, and
666
+ * {@link spellChordFromRoot} reads the letter distances back out of it; a hint
667
+ * is trusted as a whole or not at all, and only while every spelling still
668
+ * names the pitch class its interval names.
669
+ *
670
+ * @category Chords
671
+ */
672
+ type Chord = {
673
+ rootPc: number;
674
+ quality: ChordQuality;
675
+ intervals: number[];
676
+ bassPc?: number;
677
+ rootSpelling?: PitchSpelling;
678
+ bassSpelling?: PitchSpelling;
679
+ toneSpellings?: PitchSpelling[];
680
+ };
681
+ /**
682
+ * A chord positioned in time: a root pitch class and quality placed at a beat,
683
+ * with optional harmonic-analysis hints. Serves as the neutral exchange record
684
+ * between progression generators and timeline analysers.
685
+ *
686
+ * @category Composition
687
+ */
688
+ type ChordSpan = {
689
+ rootPc: number;
690
+ quality: ChordQuality;
691
+ startBeat: number;
692
+ bassPc?: number;
693
+ /**
694
+ * Semitone offsets from the root, for a chord the {@link ChordQuality} union
695
+ * cannot name exactly. Omitted for a standard chord: the template is then
696
+ * derived from `quality`, which is what every producer and consumer did
697
+ * before the field existed. Read a span with {@link chordFromSpan} so either
698
+ * case yields the same chord.
699
+ */
700
+ intervals?: number[];
701
+ /** 1-based scale degree of the chord root, when known. */
702
+ degree?: number;
703
+ /** True when the chord is a secondary dominant tonicizing another degree. */
704
+ secondaryDominant?: boolean;
705
+ };
706
+ /**
707
+ * A chord occupying a half-open beat span `[startBeat, endBeat)`.
708
+ *
709
+ * The exchange record between anything that lays chords out in time — a
710
+ * timeline analysis, a bass-line plan, an accompaniment generator — so those
711
+ * surfaces share one definition instead of agreeing by coincidence.
712
+ *
713
+ * @category Composition
714
+ */
715
+ type ChordSegment = {
716
+ startBeat: number;
717
+ endBeat: number;
718
+ chord: Chord;
719
+ };
720
+ /**
721
+ * All chord qualities the builder understands, in declaration order.
722
+ *
723
+ * The order is stable but carries no meaning: it is neither alphabetical nor
724
+ * sorted by template size. {@link detectChord} uses it as its final tie-break,
725
+ * so it is part of the observable behaviour and does not get reshuffled
726
+ * casually — but do not read it as a ranking.
727
+ *
728
+ * @category Chords
729
+ */
730
+ declare function chordQualities(): ChordQuality[];
731
+ /**
732
+ * Build a chord rooted on a diatonic scale degree.
733
+ *
734
+ * The root pitch class is the degree's diatonic pitch class in `key`, spelled
735
+ * the way the key writes it (a flat key names its degrees with flats); the
736
+ * quality's interval template is attached unchanged. Degrees beyond the scale
737
+ * length wrap around, so degree 8 of a heptatonic scale is its degree 1.
738
+ *
739
+ * @param degree 1-based scale degree of the chord root: 1 is the tonic.
740
+ * @param ext Chord quality to apply.
741
+ * @param key Key context supplying the diatonic root, as a key name, a
742
+ * key/scale, or a `Key`.
743
+ * @returns The constructed chord.
744
+ * @throws If `degree` is not a positive integer, or `ext` is not a known
745
+ * quality.
746
+ *
747
+ * @category Chords
748
+ */
749
+ declare function chordFromDegree(degree: number, ext: ChordQuality, key: SpelledKeyLike): Chord;
750
+ /**
751
+ * Build a chord from an explicit root pitch class and quality.
752
+ *
753
+ * @param rootPc Root pitch class (0..11).
754
+ * @param quality Chord quality supplying the interval template.
755
+ * @param bassPc Optional slash-chord bass pitch class.
756
+ * @returns The constructed chord.
757
+ *
758
+ * @example
759
+ * ```ts
760
+ * import { makeChord } from '@libraz/libcantus';
761
+ * const cmaj7 = makeChord(0, 'maj7');
762
+ * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
763
+ * ```
764
+ *
765
+ * @category Chords
766
+ */
767
+ declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord;
768
+ /**
769
+ * Build a chord from a {@link ChordSpec}.
770
+ *
771
+ * The structural way in, for the chords a quality name cannot reach: the tones
772
+ * come from the spec, and `quality` is the name that fits it, or the nearest
773
+ * name when none does. A chord built this way is an ordinary {@link Chord} —
774
+ * every consumer reads its `intervals` as before, and
775
+ * {@link formatChordSymbol} writes the alterations back out.
776
+ *
777
+ * @param spec The chord spec; its `rootPc`/`bassPc` become the chord's.
778
+ * @returns The constructed chord.
779
+ * @throws If any part of the spec is not one the model defines.
780
+ *
781
+ * @example
782
+ * ```ts
783
+ * import { chordFromSpec } from '@libraz/libcantus';
784
+ * chordFromSpec({
785
+ * rootPc: 0,
786
+ * base: 'maj',
787
+ * seventh: 'maj7',
788
+ * alterations: [{ degree: 11, alter: 1 }],
789
+ * additions: [],
790
+ * omissions: [],
791
+ * });
792
+ * // { rootPc: 0, quality: 'maj7#11', intervals: [0, 4, 7, 11, 18] }
793
+ * ```
794
+ *
795
+ * @category Chords
796
+ */
797
+ declare function chordFromSpec(spec: ChordSpec): Chord;
798
+ /**
799
+ * Read a chord structurally: which base, seventh, alterations and omissions it
800
+ * is made of.
801
+ *
802
+ * The reading comes from the tones themselves, so it describes a chord whatever
803
+ * built it — a parsed symbol, a detected pitch set, a span carrying a template
804
+ * no name covers. Only a template with no structural reading at all falls back
805
+ * to the one its `quality` names.
806
+ *
807
+ * @param chord The chord to read.
808
+ * @returns The spec, carrying the chord's own root and slash bass.
809
+ * @throws If the chord's template has no reading and its quality is unknown.
810
+ *
811
+ * @example
812
+ * ```ts
813
+ * import { chordSpecOf, parseChordSymbol } from '@libraz/libcantus';
814
+ * chordSpecOf(parseChordSymbol('C7(b9,#11)')).alterations;
815
+ * // [{ degree: 9, alter: -1 }, { degree: 11, alter: 1 }]
816
+ * ```
817
+ *
818
+ * @category Chords
819
+ */
820
+ declare function chordSpecOf(chord: Chord): ChordSpec;
821
+ /**
822
+ * Read a {@link ChordSpan} as a chord.
823
+ *
824
+ * The canonical way to cross from a span to a chord. A span carrying no
825
+ * `intervals` yields exactly the chord {@link makeChord} builds from its root,
826
+ * quality and bass; a span carrying an explicit template keeps it, so a color
827
+ * tone the {@link ChordQuality} union cannot name survives the trip through a
828
+ * progression, a timeline, or a generator. The template is copied, so the
829
+ * chord and the span never share an array.
830
+ *
831
+ * @param span The span to read.
832
+ * @returns The chord the span describes.
833
+ * @throws If the span's root, bass or quality is invalid, or its `intervals`
834
+ * are not a non-empty array of integer semitone offsets.
835
+ *
836
+ * @example
837
+ * ```ts
838
+ * import { chordFromSpan } from '@libraz/libcantus';
839
+ * chordFromSpan({ rootPc: 0, quality: 'maj7', startBeat: 0 });
840
+ * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
841
+ * chordFromSpan({ rootPc: 0, quality: 'maj7', startBeat: 0, intervals: [0, 4, 11, 18] });
842
+ * // the same span with a fifth-less, #11 voicing the quality cannot name
843
+ * ```
844
+ *
845
+ * @category Composition
846
+ */
847
+ declare function chordFromSpan(span: ChordSpan): Chord;
848
+ /**
849
+ * Place a chord at a beat as a {@link ChordSpan}.
850
+ *
851
+ * The interval template is recorded only when it departs from the one the
852
+ * chord's quality names, so a span built from a standard chord carries the
853
+ * same fields it always did while a custom template is not lost.
854
+ *
855
+ * @param chord The chord to place.
856
+ * @param startBeat Beat the chord starts on.
857
+ * @returns The span describing that chord at that beat.
858
+ * @throws If `startBeat` is not finite, or the chord's quality is unknown.
859
+ *
860
+ * @example
861
+ * ```ts
862
+ * import { makeChord, spanFromChord } from '@libraz/libcantus';
863
+ * spanFromChord(makeChord(0, 'maj7'), 4);
864
+ * // { rootPc: 0, quality: 'maj7', startBeat: 4 } — no intervals for a standard chord
865
+ * ```
866
+ *
867
+ * @category Composition
868
+ */
869
+ declare function spanFromChord(chord: Chord, startBeat: number): ChordSpan;
870
+ /**
871
+ * Transpose a chord by a number of semitones.
872
+ *
873
+ * The interval template is carried over untouched, so a chord whose intervals
874
+ * were customised keeps them, and a slash bass moves with the root. Enharmonic
875
+ * spelling hints are dropped rather than shifted: the letter a transposed root
876
+ * should take depends on the destination key, which a semitone count does not
877
+ * carry. Pass the result through {@link spellChord} to respell it.
878
+ *
879
+ * @param chord The chord to transpose.
880
+ * @param semitones The signed semitone offset.
881
+ * @returns The transposed chord.
882
+ * @throws If `semitones` is not finite.
883
+ *
884
+ * @example
885
+ * ```ts
886
+ * import { formatChordSymbol, parseChordSymbol, transposeChord } from '@libraz/libcantus';
887
+ * formatChordSymbol(transposeChord(parseChordSymbol('C/G'), 2)); // 'D/A'
888
+ * ```
889
+ *
890
+ * @category Chords
891
+ */
892
+ declare function transposeChord(chord: Chord, semitones: number): Chord;
893
+ /**
894
+ * Get the sorted, deduplicated pitch classes of a chord.
895
+ *
896
+ * A slash bass is one of them: `F/G` sounds a G, the voicers put it in the
897
+ * bass, and a set that omitted it would not re-detect as the chord it came
898
+ * from. Pass `includeBass: false` to enumerate the interval template alone.
899
+ *
900
+ * @param chord The chord to enumerate.
901
+ * @param opts Set `includeBass: false` to omit a slash bass.
902
+ * @returns The chord's pitch classes, sorted ascending in [0, 11].
903
+ *
904
+ * @example
905
+ * ```ts
906
+ * import { makeChord, chordPitchClasses } from '@libraz/libcantus';
907
+ * chordPitchClasses(makeChord(0, 'maj7')); // [0, 4, 7, 11]
908
+ * chordPitchClasses(makeChord(5, 'maj', 7)); // [0, 5, 7, 9] — F/G, G included
909
+ * ```
910
+ *
911
+ * @category Chords
912
+ */
913
+ declare function chordPitchClasses(chord: Chord, opts?: {
914
+ includeBass?: boolean;
915
+ }): number[];
916
+ /**
917
+ * A pitch's interval class above the chord root, in [0, 11].
918
+ *
919
+ * The shared reading of "where does this pitch sit in the chord", used by the
920
+ * safety evaluator and the voice analyser alike so they cannot disagree.
921
+ *
922
+ * @param pitch MIDI pitch or bare pitch class.
923
+ * @param chord The chord providing the root reference.
924
+ * @returns The interval class above the root.
925
+ * @category Chords
926
+ */
927
+ declare function intervalAboveRoot(pitch: number, chord: Chord): number;
928
+ /**
929
+ * Whether a pitch is one of a chord's tones, ignoring octave.
930
+ *
931
+ * @param pitch MIDI pitch or bare pitch class.
932
+ * @param chord The chord, or null for no sounding harmony.
933
+ * @returns True when the pitch class belongs to the chord.
934
+ * @category Chords
935
+ */
936
+ declare function isChordMember(pitch: number, chord: Chord | null): boolean;
937
+ /**
938
+ * Determine a pitch's harmonic role within a chord.
939
+ *
940
+ * A chord carrying its own tone spellings is read by them, since the degree it
941
+ * writes a tone as is the degree that tone plays: the ten semitones above the
942
+ * root of a German sixth are written five letters up, so they are its sixth and
943
+ * not a seventh owing a step downward. Everywhere else the role is derived from
944
+ * the pitch's interval above the chord root, reduced modulo 12. A major sixth
945
+ * (9) reads as a `sixth` for sixth chords but as a `seventh` for a
946
+ * diminished-seventh chord; ninths and other tensions have no basic role and
947
+ * return null.
948
+ *
949
+ * @param pitch MIDI pitch or bare pitch class.
950
+ * @param chord The chord providing the root reference.
951
+ * @returns The chord-tone role, or null if the pitch has no basic role.
952
+ *
953
+ * @category Chords
954
+ */
955
+ declare function chordToneRole(pitch: number, chord: Chord): ChordToneRole | null;
956
+ /**
957
+ * Build the diatonic triad rooted on a scale degree by stacking scale thirds.
958
+ *
959
+ * Unlike {@link chordFromDegree}, the chord quality is derived from the scale
960
+ * rather than supplied, so degrees yield their scale-correct triads (e.g. a
961
+ * diminished triad on the leading tone of a major key).
962
+ * The root is spelled the way the key writes it.
963
+ *
964
+ * @param degree 1-based scale degree of the chord root: 1 is the tonic.
965
+ * @param key Key/scale context, as a key name, a key/scale, or a `Key`.
966
+ * @returns The diatonic triad.
967
+ * @throws If the scale is not heptatonic. Stacking thirds means skipping every
968
+ * other degree, which only lands on a triad when there are seven of them, so
969
+ * the pentatonic, blues, whole-tone, octatonic and chromatic scales have no
970
+ * diatonic triad; use {@link chordFromDegree} with an explicit quality there.
971
+ *
972
+ * @example
973
+ * ```ts
974
+ * import { majorKey, diatonicTriad } from '@libraz/libcantus';
975
+ * const tonic = diatonicTriad(1, majorKey(0)); // C major triad (degree 1 of C major)
976
+ * ```
977
+ *
978
+ * @category Chords
979
+ */
980
+ declare function diatonicTriad(degree: number, key: SpelledKeyLike): Chord;
981
+ /**
982
+ * Build the diatonic seventh chord rooted on a scale degree.
983
+ *
984
+ * The root is spelled the way the key writes it.
985
+ *
986
+ * @param degree 1-based scale degree of the chord root: 1 is the tonic.
987
+ * @param key Key/scale context, as a key name, a key/scale, or a `Key`.
988
+ * @returns The diatonic seventh chord.
989
+ * @throws If the scale is not heptatonic, for the reason given on
990
+ * {@link diatonicTriad}.
991
+ *
992
+ * @category Chords
993
+ */
994
+ declare function diatonicSeventh(degree: number, key: SpelledKeyLike): Chord;
995
+
996
+ /**
997
+ * Style policy: `strict` counterpoint vs. `pop` voice leading.
998
+ *
999
+ * A profile says two things. It sets the severity of each reason
1000
+ * {@link evaluateSafety} finds, which decides what is rejected outright, and it
1001
+ * carries the {@link ProfileWeights} that rank whatever survives — because most
1002
+ * of what separates the two styles is preference rather than prohibition.
1003
+ *
1004
+ * @category Arrangement & Analysis
1005
+ */
1006
+ type SafetyProfile = 'strict' | 'pop';
1007
+ /**
1008
+ * How a profile ranks the candidates its severity table has let through.
1009
+ *
1010
+ * Each field is a score contribution, added when the situation it names occurs;
1011
+ * a negative value is a penalty. The scale is arbitrary but shared, so only the
1012
+ * relative sizes matter. Nothing here can make an unsafe pitch usable: rejection
1013
+ * is the severity table's business, and these weights only order what is left.
1014
+ *
1015
+ * @category Arrangement & Analysis
1016
+ */
1017
+ type ProfileWeights = {
1018
+ /** A third or a sixth against the other voice. */
1019
+ imperfectConsonance: number;
1020
+ /** A unison, fifth or octave against the other voice. */
1021
+ perfectConsonance: number;
1022
+ /** A second, seventh or tritone against the other voice. */
1023
+ dissonance: number;
1024
+ /** The candidate belongs to the sounding chord. */
1025
+ chordTone: number;
1026
+ /** The two voices move in opposite directions. */
1027
+ contraryMotion: number;
1028
+ /** One voice holds while the other moves. */
1029
+ obliqueMotion: number;
1030
+ /** Both voices move the same way into a different interval. */
1031
+ similarMotion: number;
1032
+ /** Both voices move the same way, keeping the same imperfect consonance. */
1033
+ parallelImperfect: number;
1034
+ /** The candidate is a step from the previous note of its own line. */
1035
+ stepwise: number;
1036
+ /** Per semitone of melodic movement, so a leap costs more than a step. */
1037
+ melodicDistance: number;
1038
+ /** The move is a leap strict counterpoint forbids outright. */
1039
+ forbiddenLeap: number;
1040
+ /** Per semitone away from the centre of the line's register. */
1041
+ registerDrift: number;
1042
+ };
1043
+ /**
1044
+ * The weight table each profile ranks candidates by.
1045
+ *
1046
+ * `strict` states the sixteenth-century preferences: contrary motion is worth
1047
+ * seeking, similar motion is worth avoiding, imperfect consonances carry the
1048
+ * line, and a run of parallel thirds earns nothing. `pop` inverts two of those.
1049
+ * Parallel thirds and sixths are the harmony line an arranger writes on purpose,
1050
+ * a pedal or a held unison under a moving lead is a texture rather than a fault,
1051
+ * and similar motion is simply how two parts often move together — while a bass
1052
+ * moving against the lead is still worth preferring where it is available.
1053
+ *
1054
+ * @category Arrangement & Analysis
1055
+ */
1056
+ declare const PROFILE_WEIGHTS: Readonly<Record<SafetyProfile, Readonly<ProfileWeights>>>;
1057
+ /**
1058
+ * Resolve a profile to the weights that rank its candidates, with per-field
1059
+ * overrides applied on top.
1060
+ *
1061
+ * @param profile The profile whose table to start from.
1062
+ * @param overrides Fields to replace; anything absent keeps the profile's value.
1063
+ * A field written as an explicit `undefined` is absent, not a replacement.
1064
+ * @returns The complete weight table to score with.
1065
+ * @throws If `profile` is not one of the profile names, or an override is not a
1066
+ * finite number ({@link InvalidInputError}). A misspelled profile scored under
1067
+ * a default table would rank candidates by a style the caller did not ask for,
1068
+ * and a single non-finite weight poisons every candidate's score, which turns
1069
+ * the ranking into the order the candidates happened to be enumerated in.
1070
+ * @example
1071
+ * ```ts
1072
+ * import { profileWeights } from '@libraz/libcantus';
1073
+ * profileWeights('pop', { parallelImperfect: 4 }).contraryMotion; // 1.5 — the rest is untouched
1074
+ * ```
1075
+ * @category Arrangement & Analysis
1076
+ */
1077
+ declare function profileWeights(profile: SafetyProfile, overrides?: Partial<ProfileWeights>): ProfileWeights;
1078
+ /**
1079
+ * Overall placeability verdict for a candidate pitch.
1080
+ *
1081
+ * @category Arrangement & Analysis
1082
+ */
1083
+ declare enum NoteSafety {
1084
+ Safe = 0,
1085
+ Warning = 1,
1086
+ Dissonant = 2
1087
+ }
1088
+ /**
1089
+ * Bit flags describing why a pitch received its verdict.
1090
+ *
1091
+ * Several flags can describe one pitch, so test the combination rather than a
1092
+ * flag alone: an avoid eleventh carries `Tension` as well as `AvoidNote`, and a
1093
+ * usable tension is `Tension` without `AvoidNote`. `ChordTone`, `MinorSecond`
1094
+ * and `MajorSeventh` are informational and never lower the verdict on their
1095
+ * own; every other flag sets at least a warning, and the profile decides how
1096
+ * far past that it goes.
1097
+ *
1098
+ * @category Arrangement & Analysis
1099
+ */
1100
+ declare enum ReasonFlag {
1101
+ /** The candidate is a member of the chord. Informational. */
1102
+ ChordTone = 1,
1103
+ /**
1104
+ * The candidate is a ninth, eleventh or thirteenth above the root, not a chord
1105
+ * tone. Also set alongside `AvoidNote` when the avoid note is the eleventh.
1106
+ */
1107
+ Tension = 2,
1108
+ /**
1109
+ * The eleventh over a chord with a major third and no fourth, or the major
1110
+ * seventh over a dominant. Always set with `NeedsResolution`, and with
1111
+ * `Tension` for the eleventh.
1112
+ */
1113
+ AvoidNote = 4,
1114
+ /** The candidate is in the key but neither a chord tone nor a tension. */
1115
+ ScaleTone = 8,
1116
+ /** The candidate is outside the key and not a chord tone. */
1117
+ NonScale = 16,
1118
+ /** The candidate lies outside `vocalLow`..`vocalHigh`. */
1119
+ OutOfRange = 32,
1120
+ /** The candidate, not itself a chord tone, is a tritone from one. */
1121
+ Tritone = 64,
1122
+ /**
1123
+ * The move from `prevPitch` is a forbidden melodic leap as
1124
+ * {@link isForbiddenMelodicLeap} defines it: a tritone, either seventh, or
1125
+ * anything wider than an octave. An octave itself is not. The profile sets
1126
+ * the severity, not the set of leaps. Set with `MelodicTritone` on a tritone
1127
+ * and with `MajorSeventh` on a major seventh.
1128
+ */
1129
+ LargeLeap = 128,
1130
+ /** The move from `prevPitch` reduces to a semitone, the minor ninth included. Informational. */
1131
+ MinorSecond = 256,
1132
+ /** The move from `prevPitch` reduces to a major seventh; always with `LargeLeap`. Informational. */
1133
+ MajorSeventh = 512,
1134
+ /**
1135
+ * On a strong beat, the candidate is dissonant against at least one of
1136
+ * `otherVoices`, apart from the tritone or seventh two chord tones spell. A
1137
+ * perfect fourth counts only when one of the two is the lowest sounding voice,
1138
+ * and under `pop` not when both are chord tones — an inverted chord.
1139
+ */
1140
+ VerticalDissonance = 1024,
1141
+ /** The candidate moves in parallel perfect intervals with at least one of `otherVoices`. */
1142
+ ParallelPerfect = 2048,
1143
+ /**
1144
+ * The candidate and another voice, the two outer voices of the texture, reach
1145
+ * a perfect interval by similar motion with the upper one leaping.
1146
+ */
1147
+ HiddenParallel = 4096,
1148
+ /** The candidate crosses at least one of `otherVoices` since the previous step. */
1149
+ VoiceCrossing = 8192,
1150
+ /**
1151
+ * A held pitch, consonant with a voice on the previous step, now dissonant
1152
+ * against it. Always with `VerticalDissonance`.
1153
+ */
1154
+ Suspension = 16384,
1155
+ /** The candidate should move by step to `resolveTo`. Set with `AvoidNote`. */
1156
+ NeedsResolution = 32768,
1157
+ /** The move from `prevPitch` reduces to a tritone; always with `LargeLeap`. */
1158
+ MelodicTritone = 65536
1159
+ }
1160
+ /**
1161
+ * A neighbouring voice's current and previous pitch.
1162
+ *
1163
+ * @category Arrangement & Analysis
1164
+ */
1165
+ type VoiceSnapshot = {
1166
+ pitch: number;
1167
+ prevPitch?: number;
1168
+ };
1169
+ /**
1170
+ * Everything needed to evaluate one candidate pitch.
1171
+ *
1172
+ * @category Arrangement & Analysis
1173
+ */
1174
+ type SafetyQuery = {
1175
+ profile: SafetyProfile;
1176
+ candidatePitch: number;
1177
+ prevPitch?: number;
1178
+ chord: Chord | null;
1179
+ key: KeyScale;
1180
+ otherVoices: VoiceSnapshot[];
1181
+ strongBeat: boolean;
1182
+ vocalLow?: number;
1183
+ vocalHigh?: number;
1184
+ };
1185
+ /**
1186
+ * The reasons one of `otherVoices` contributes to a verdict.
1187
+ *
1188
+ * @category Arrangement & Analysis
1189
+ */
1190
+ type SafetyPartner = {
1191
+ /** The voice's index in {@link SafetyQuery.otherVoices}. */
1192
+ index: number;
1193
+ /**
1194
+ * The pairwise flags this voice raises: `VerticalDissonance`, `Suspension`,
1195
+ * `ParallelPerfect`, `HiddenParallel` and `VoiceCrossing`.
1196
+ */
1197
+ reasons: number;
1198
+ };
1199
+ /**
1200
+ * The verdict, reason flags, and optional resolution guidance.
1201
+ *
1202
+ * @category Arrangement & Analysis
1203
+ */
1204
+ type SafetyResult = {
1205
+ safety: NoteSafety;
1206
+ reasons: number;
1207
+ resolveTo?: number;
1208
+ suggestions?: number[];
1209
+ /**
1210
+ * The voices behind the pairwise flags in `reasons`, in `otherVoices` order,
1211
+ * when {@link EvaluateSafetyOptions.partners} asked for them and any voice
1212
+ * raised one. Their `reasons` together are exactly the pairwise flags set.
1213
+ */
1214
+ partners?: SafetyPartner[];
1215
+ rationale?: string;
1216
+ };
1217
+ /**
1218
+ * Evaluate the safety of placing a candidate pitch in a voice.
1219
+ *
1220
+ * Reasons are merged from harmonic context (chord tone / tension / avoid / scale)
1221
+ * and counterpoint (vertical dissonance, parallels, voice crossing). The `strict`
1222
+ * profile treats avoid notes and parallels as dissonant; `pop` treats them as
1223
+ * warnings. The final verdict is the worst severity among the reasons.
1224
+ *
1225
+ * @param q The candidate and its harmonic/voice-leading context.
1226
+ * @returns The verdict, reason bitmask, and optional resolution guidance.
1227
+ * @throws If the profile is not one of the profile names, or if any pitch in
1228
+ * the query is not a MIDI pitch in 0..127 ({@link InvalidInputError}).
1229
+ * @example
1230
+ * ```ts
1231
+ * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';
1232
+ * const result = evaluateSafety({
1233
+ * profile: 'pop',
1234
+ * candidatePitch: 60, // C over a C major chord
1235
+ * chord: makeChord(0, 'maj'),
1236
+ * key: majorKey(0),
1237
+ * otherVoices: [],
1238
+ * strongBeat: true,
1239
+ * });
1240
+ * result.safety === NoteSafety.Safe; // true — C is a chord tone
1241
+ * ```
1242
+ * @category Arrangement & Analysis
1243
+ */
1244
+ declare function evaluateSafety(q: SafetyQuery, opts?: EvaluateSafetyOptions): SafetyResult;
1245
+ /**
1246
+ * Options for {@link evaluateSafety}.
1247
+ *
1248
+ * @category Arrangement & Analysis
1249
+ */
1250
+ type EvaluateSafetyOptions = {
1251
+ /**
1252
+ * Whether to search for safe replacement pitches when the verdict is not
1253
+ * safe. Turning it off skips up to two dozen extra evaluations per rejected
1254
+ * pitch, which is worth doing when only the verdict is wanted.
1255
+ *
1256
+ * @defaultValue true
1257
+ */
1258
+ suggestions?: boolean;
1259
+ /**
1260
+ * Whether to report which of `otherVoices` raised each pairwise flag, as
1261
+ * {@link SafetyResult.partners}. The bitmask alone says a parallel fifth is
1262
+ * there; this says against which voice.
1263
+ *
1264
+ * @defaultValue false
1265
+ */
1266
+ partners?: boolean;
1267
+ };
1268
+ /**
1269
+ * Enumerate placeable pitches in a range, chord tones first, descending.
1270
+ *
1271
+ * @param q The safety context minus the candidate pitch.
1272
+ * @param pitchLow Lowest MIDI pitch to consider (inclusive).
1273
+ * @param pitchHigh Highest MIDI pitch to consider (inclusive).
1274
+ * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
1275
+ * @throws If either bound is not a MIDI pitch in 0..127, reversed, or exceeds
1276
+ * the generation budget, or if the context names an unknown profile.
1277
+ * @example
1278
+ * ```ts
1279
+ * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
1280
+ * const pitches = enumerateSafePitches(
1281
+ * { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },
1282
+ * 60,
1283
+ * 72,
1284
+ * );
1285
+ * pitches; // placeable pitches in [60, 72], chord tones first, each group descending
1286
+ * ```
1287
+ * @category Arrangement & Analysis
1288
+ */
1289
+ declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
1290
+
1291
+ /**
1292
+ * Reading a caller's chord into the one shape the library works in.
1293
+ *
1294
+ * The widening counterpart of the other `to*Data` coercers, kept beside the
1295
+ * grammar it falls back on rather than inside it: what a chord symbol means is
1296
+ * the parser's question, and what shapes stand for a chord is this one's.
1297
+ */
1298
+ /**
1299
+ * Anything that names a chord: a chord symbol, plain chord data, or a value
1300
+ * that serializes to chord data such as the `Chord` class.
1301
+ *
1302
+ * A value that also holds its chord as `data`, as the `Chord` class does, is
1303
+ * read through that: the chord as it prints, spelled by the key it carries.
1304
+ *
1305
+ * @category Chords
1306
+ */
1307
+ type ChordLike = string | Chord | {
1308
+ /** The chord data this value stands for. */
1309
+ toJSON(): Chord;
1310
+ };
1311
+ /**
1312
+ * Resolve any chord-shaped value to plain {@link Chord} data.
1313
+ *
1314
+ * The counterpart of {@link toSpelledInterval} for chords: an entry point takes
1315
+ * whatever form the caller has — the symbol a chart holds, the data the chord
1316
+ * module returns, or a `Chord` instance — and gets one shape back. An instance
1317
+ * is accepted through its `toJSON` method rather than by its type, so the
1318
+ * layers below the model can read a class without importing it.
1319
+ *
1320
+ * @param value A chord symbol, plain chord data, or a value whose `data` or
1321
+ * `toJSON` returns chord data.
1322
+ * @returns The validated chord data, with root and bass reduced to pitch
1323
+ * classes and any spelling hint carried through.
1324
+ * @throws If the value names no chord, or an interval, root, or bass is not a
1325
+ * finite number.
1326
+ * @example
1327
+ * ```ts
1328
+ * import { toChordData } from '@libraz/libcantus';
1329
+ * toChordData('Cmaj7').intervals; // [0, 4, 7, 11]
1330
+ * toChordData({ rootPc: 0, quality: 'maj', intervals: [0, 4, 7] }).rootPc; // 0
1331
+ * ```
1332
+ * @category Chords
1333
+ */
1334
+ declare function toChordData(value: ChordLike): Chord;
1335
+
1336
+ export { subdominantKeyOf as $, chordSpecQuality as B, chordToneRole as D, diatonicSeventh as F, diatonicTriad as G, dominantKeyOf as H, enharmonicKeyOf as I, enumerateSafePitches as J, evaluateSafety as L, intervalAboveRoot as M, NoteSafety as N, isChordMember as O, PROFILE_WEIGHTS as P, keyRelationBetween as Q, ReasonFlag as R, makeChord as T, parallelKeyOf as U, profileWeights as W, relatedKeysOf as X, relativeKeyOf as Y, spanFromChord as Z, spelledKeyOf as _, toChordData as a0, toKeyScale as a1, transposeChord as a2, chordFromDegree as t, chordFromSpan as u, chordFromSpec as v, chordPitchClasses as w, chordQualities as x, chordSpecIntervals as y, chordSpecOf as z };
1337
+ export type { Alteration as A, ChordBase as C, EvaluateSafetyOptions as E, KeyLike as K, SafetyPartner as S, VoiceSnapshot as V, AlteredDegree as a, Chord as b, ChordLike as c, ChordQuality as d, ChordSegment as e, ChordSeventh as f, ChordSpan as g, ChordSpec as h, ChordToneRole as i, KeyRelation as j, KeyVariant as k, PitchSpelling as l, ProfileWeights as m, ResolvedKey as n, SafetyProfile as o, SafetyQuery as p, SafetyResult as q, SpelledKeyLike as r, SpelledKeyScale as s };