@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.
- package/LICENSE +201 -0
- package/NOTICE +63 -0
- package/README.md +65 -2
- package/dist/analyze/index.d.ts +341 -0
- package/dist/analyze/index.js +128 -0
- package/dist/backend.js +140 -0
- package/dist/cantus.js +2 -0
- package/dist/cantus.wasm +0 -0
- package/dist/chunk-4LABHUBW.js +6940 -0
- package/dist/coerce-CUhHc3Tu.d.ts +1337 -0
- package/dist/core/index.d.ts +293 -0
- package/dist/core/index.js +224 -0
- package/dist/generate/index.d.ts +808 -0
- package/dist/generate/index.js +150 -0
- package/dist/index-BLuDesVG.d.ts +1339 -0
- package/dist/index-Bf0Sv8a9.d.ts +514 -0
- package/dist/index-C7KCaTRz.d.ts +64 -0
- package/dist/index-C9MYbuKS.d.ts +804 -0
- package/dist/index-DInQqT8Q.d.ts +66 -0
- package/dist/index-Dg-SAfhz.d.ts +663 -0
- package/dist/index-jgeug9EA.d.ts +2894 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +802 -0
- package/dist/masks-tycmkrgs.d.ts +493 -0
- package/dist/model/index.d.ts +5964 -0
- package/dist/model/index.js +46 -0
- package/dist/positional-DLnfUgqG.d.ts +365 -0
- package/dist/profile-B4WqcM4H.d.ts +1508 -0
- package/dist/theory/index.d.ts +992 -0
- package/dist/theory/index.js +288 -0
- package/dist/types-7mGFwvMm.d.ts +2599 -0
- package/package.json +93 -4
|
@@ -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 };
|