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