@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,992 @@
|
|
|
1
|
+
import { e as KeyScale, j as NoteNameOptions, P as ParseResult, S as SpelledInterval, g as Note, i as NoteLike } from '../index-C9MYbuKS.js';
|
|
2
|
+
export { B as BudgetExceededError, I as IntervalData, b as IntervalLike, c as IntervalQualityLabel, d as InvalidInputError, L as LibcantusError, N as NoSolutionError, k as NoteNameSystem } from '../index-C9MYbuKS.js';
|
|
3
|
+
import { C as ConsonanceClass } from '../index-DInQqT8Q.js';
|
|
4
|
+
import { K as KeyLike, n as ResolvedKey, s as SpelledKeyScale, c as ChordLike, b as Chord, r as SpelledKeyLike } from '../coerce-CUhHc3Tu.js';
|
|
5
|
+
export { A as Alteration, a as AlteredDegree, C as ChordBase, d as ChordQuality, e as ChordSegment, f as ChordSeventh, g as ChordSpan, h as ChordSpec, i as ChordToneRole, E as EvaluateSafetyOptions, j as KeyRelation, k as KeyVariant, N as NoteSafety, P as PROFILE_WEIGHTS, l as PitchSpelling, m as ProfileWeights, R as ReasonFlag, S as SafetyPartner, o as SafetyProfile, p as SafetyQuery, q as SafetyResult, V as VoiceSnapshot, t as chordFromDegree, u as chordFromSpan, v as chordFromSpec, w as chordPitchClasses, x as chordQualities, y as chordSpecIntervals, z as chordSpecOf, B as chordSpecQuality, D as chordToneRole, F as diatonicSeventh, G as diatonicTriad, H as dominantKeyOf, I as enharmonicKeyOf, J as enumerateSafePitches, L as evaluateSafety, M as intervalAboveRoot, O as isChordMember, Q as keyRelationBetween, T as makeChord, U as parallelKeyOf, W as profileWeights, X as relatedKeysOf, Y as relativeKeyOf, Z as spanFromChord, _ as spelledKeyOf, $ as subdominantKeyOf, a0 as toChordData, a1 as toKeyScale, a2 as transposeChord } from '../coerce-CUhHc3Tu.js';
|
|
6
|
+
import { r as VoicingOptions } from '../index-BLuDesVG.js';
|
|
7
|
+
export { A as AvailableTensionsOptions, a as AvoidNoteUse, b as AvoidNotesOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, d as ChordSymbolOptions, K as KeyMode, P as PartWritingOptions, e as PartWritingViolation, f as PartWritingViolationKind, S as SATB_RANGES, g as SCALE_SYSTEMS, h as ScaleChoice, i as ScaleSystem, j as Species, k as SpeciesOptions, l as SpelledVoicing, m as StyledVoicingOptions, T as TRANSPOSING_INSTRUMENTS, n as TransposingInstrument, o as TransposingInstrumentName, V as VoiceIndependenceOptions, p as VoiceIndependenceReport, q as VoiceRange, s as VoicingStyle, t as availableTensions, u as avoidNotes, v as checkPartWriting, w as checkSpecies, x as chordScaleReport, y as chordScales, z as formatChordSymbol, B as instrumentTransposition, D as isSignatureKey, E as keyFromFifths, F as keySignatureFifths, G as parseChordSymbol, H as scaleMatchesChord, I as scaleSystemOf, J as scalesForChanges, L as spellVoicing, M as supportsFunctionalHarmony, N as toSoundingPitch, O as toWrittenPitch, Q as transposeChordSymbol, R as tryParseChordSymbol, U as voiceChord, W as voiceChordStyled, X as voiceIndependence, Y as voiceProgression } from '../index-BLuDesVG.js';
|
|
8
|
+
export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-C7KCaTRz.js';
|
|
9
|
+
import { s as ScaleNameInput } from '../masks-tycmkrgs.js';
|
|
10
|
+
export { A as ALTERED_MASK, B as BLUES_MASK, C as CHROMATIC_MASK, D as DORIAN_MASK, a as DOUBLE_HARMONIC_MASK, H as HARMONIC_MINOR_MASK, L as LOCRIAN_MASK, b as LOCRIAN_NATURAL2_MASK, c as LYDIAN_DOMINANT_MASK, d as LYDIAN_MASK, M as MAJOR_MASK, e as MAJOR_PENTATONIC_MASK, f as MARWA_MASK, g as MELODIC_MINOR_MASK, h as MINOR_PENTATONIC_MASK, i as MIXOLYDIAN_B13_MASK, j as MIXOLYDIAN_MASK, k as MIYAKO_BUSHI_MASK, N as NAMED_SCALES, l as NATURAL_MINOR_MASK, O as OCTATONIC_HALF_WHOLE_MASK, m as OCTATONIC_WHOLE_HALF_MASK, P as PHRYGIAN_DOMINANT_MASK, n as PHRYGIAN_MASK, o as PURVI_MASK, R as RITSU_MASK, p as RYUKYU_MASK, S as SCALE_ALIASES, q as ScaleAliasName, r as ScaleName, T as TODI_MASK, W as WHOLE_TONE_MASK, t as WORLD_SCALES, u as WorldScaleName, v as assertKeyVariant, w as assertModeMask, x as maskFromOffsets, y as namedScaleMask, z as requireScaleMask, E as resolveScaleName, F as variantOfMask } from '../masks-tycmkrgs.js';
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Test whether a pitch belongs to the scale.
|
|
14
|
+
*
|
|
15
|
+
* @param pitch MIDI pitch or bare pitch class.
|
|
16
|
+
* @param key The key/scale to test against, as a key name, a key/scale, or a
|
|
17
|
+
* `Key`.
|
|
18
|
+
* @returns True if the pitch class is a member of the scale.
|
|
19
|
+
*
|
|
20
|
+
* @example
|
|
21
|
+
* ```ts
|
|
22
|
+
* import { majorKey, isScaleTone } from '@libraz/libcantus';
|
|
23
|
+
* const key = majorKey(0); // C major
|
|
24
|
+
* isScaleTone(64, key); // true — E is in C major
|
|
25
|
+
* isScaleTone(61, key); // false — C# is not
|
|
26
|
+
* ```
|
|
27
|
+
*
|
|
28
|
+
* @category Scales
|
|
29
|
+
*/
|
|
30
|
+
declare function isScaleTone(pitch: number, key: KeyLike): boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Find the nearest MIDI pitch whose pitch class is in the scale.
|
|
33
|
+
*
|
|
34
|
+
* The search expands symmetrically outward from `pitch`. On a tie (equal
|
|
35
|
+
* distance above and below) the lower pitch is returned.
|
|
36
|
+
*
|
|
37
|
+
* @param pitch MIDI pitch to snap.
|
|
38
|
+
* @param key The key/scale to snap to, as a key name, a key/scale, or a `Key`.
|
|
39
|
+
* @returns The nearest in-scale MIDI pitch.
|
|
40
|
+
*
|
|
41
|
+
* @category Scales
|
|
42
|
+
*/
|
|
43
|
+
declare function nearestScaleTone(pitch: number, key: KeyLike): number;
|
|
44
|
+
/**
|
|
45
|
+
* Where a pitch sits on the key's ladder of scale tones.
|
|
46
|
+
*
|
|
47
|
+
* `rung` counts scale tones from the tonic and continues across octaves, so
|
|
48
|
+
* adding to it moves by scale degrees; it is negative below the tonic of octave
|
|
49
|
+
* 0. `offset` is how many semitones the pitch sounds above that rung, which is 0
|
|
50
|
+
* for a scale tone and positive for one between two of them.
|
|
51
|
+
*/
|
|
52
|
+
type ScaleLadderPosition = {
|
|
53
|
+
rung: number;
|
|
54
|
+
offset: number;
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* Locate a pitch on the key's ladder of scale tones.
|
|
58
|
+
*
|
|
59
|
+
* Anything counting in scale degrees has to put a pitch on this ladder and back
|
|
60
|
+
* again afterwards. Keeping the chromatic offset apart from the rung is what
|
|
61
|
+
* lets a note between two scale tones survive the arithmetic as the note it was:
|
|
62
|
+
* without it a shift by any number of degrees — including none — would first
|
|
63
|
+
* flatten every chromatic pitch onto the scale.
|
|
64
|
+
*
|
|
65
|
+
* In C major, C# sits on the tonic's rung with an offset of one semitone.
|
|
66
|
+
*
|
|
67
|
+
* Layer-internal: the generators count degrees with it, and callers reach the
|
|
68
|
+
* same arithmetic through the transforms that use it.
|
|
69
|
+
*
|
|
70
|
+
* @param pitch MIDI pitch.
|
|
71
|
+
* @param key The key/scale to count along, as a key name, a key/scale, or a
|
|
72
|
+
* `Key`.
|
|
73
|
+
* @returns The rung the pitch sits on and its semitone offset above it.
|
|
74
|
+
*/
|
|
75
|
+
declare function scaleLadderPosition(pitch: number, key: KeyLike): ScaleLadderPosition;
|
|
76
|
+
/**
|
|
77
|
+
* The pitch a rung of the key's ladder of scale tones stands for.
|
|
78
|
+
*
|
|
79
|
+
* The inverse of {@link scaleLadderPosition}'s `rung`: adding the position's
|
|
80
|
+
* `offset` back to the result returns the pitch it came from.
|
|
81
|
+
*
|
|
82
|
+
* Layer-internal, like {@link scaleLadderPosition}.
|
|
83
|
+
*
|
|
84
|
+
* @param rung Scale tones counted from the tonic, negative below it.
|
|
85
|
+
* @param key The key/scale to count along, as a key name, a key/scale, or a
|
|
86
|
+
* `Key`.
|
|
87
|
+
* @returns The MIDI pitch of that scale tone.
|
|
88
|
+
*/
|
|
89
|
+
declare function scaleLadderPitch(rung: number, key: KeyLike): number;
|
|
90
|
+
/**
|
|
91
|
+
* Shift a pitch by scale degrees along the key's ladder of scale tones.
|
|
92
|
+
*
|
|
93
|
+
* A pitch between two scale tones keeps its distance above the one below it, so
|
|
94
|
+
* a chromatic passing note is still a chromatic passing note after the shift,
|
|
95
|
+
* and a shift of no degrees returns the pitch untouched: a step up the C-major
|
|
96
|
+
* ladder answers C# with D#, not with D.
|
|
97
|
+
*
|
|
98
|
+
* Layer-internal. It is what `transposeDiatonic` and a tonal imitation both
|
|
99
|
+
* count along, so the two answer the same shift the same way; a caller reaches
|
|
100
|
+
* it through either of them.
|
|
101
|
+
*
|
|
102
|
+
* @param pitch MIDI pitch to shift.
|
|
103
|
+
* @param degrees Scale degrees to move by; negative moves down.
|
|
104
|
+
* @param key The key/scale to count along, as a key name, a key/scale, or a
|
|
105
|
+
* `Key`.
|
|
106
|
+
* @returns The shifted pitch.
|
|
107
|
+
*/
|
|
108
|
+
declare function shiftByScaleDegrees(pitch: number, degrees: number, key: KeyLike): number;
|
|
109
|
+
/**
|
|
110
|
+
* Get the scale degree of a pitch, counted from 1: the tonic is degree 1.
|
|
111
|
+
*
|
|
112
|
+
* A pitch outside the scale answers -1 rather than 0, so a caller testing the
|
|
113
|
+
* result for a degree cannot mistake the "not in the scale" answer for the
|
|
114
|
+
* tonic.
|
|
115
|
+
*
|
|
116
|
+
* @param pitch MIDI pitch or bare pitch class.
|
|
117
|
+
* @param key The key/scale to measure against, as a key name, a key/scale, or a
|
|
118
|
+
* `Key`.
|
|
119
|
+
* @returns The 1-based degree, or -1 if the pitch is not in the scale.
|
|
120
|
+
*
|
|
121
|
+
* @category Scales
|
|
122
|
+
*/
|
|
123
|
+
declare function pitchToScaleDegree(pitch: number, key: KeyLike): number;
|
|
124
|
+
/**
|
|
125
|
+
* List the pitch classes of a key's scale.
|
|
126
|
+
*
|
|
127
|
+
* @param key The key/scale to enumerate, as a key name, a key/scale, or a `Key`.
|
|
128
|
+
* @returns The member pitch classes, sorted ascending in [0, 11].
|
|
129
|
+
*
|
|
130
|
+
* @category Scales
|
|
131
|
+
*/
|
|
132
|
+
declare function diatonicPitchClasses(key: KeyLike): number[];
|
|
133
|
+
/**
|
|
134
|
+
* List the pitch classes of a key's scale in ascending scale-degree order.
|
|
135
|
+
*
|
|
136
|
+
* The first entry is the root (degree 1); degrees follow the mask bits in
|
|
137
|
+
* offset order rather than sorted pitch-class order.
|
|
138
|
+
*
|
|
139
|
+
* @param key The key/scale to enumerate, as a key name, a key/scale, or a `Key`.
|
|
140
|
+
* @returns The member pitch classes ordered by scale degree.
|
|
141
|
+
*
|
|
142
|
+
* @category Scales
|
|
143
|
+
*/
|
|
144
|
+
declare function scaleTonesInDegreeOrder(key: KeyLike): number[];
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Resolve any key-shaped value to the whole key it names.
|
|
148
|
+
*
|
|
149
|
+
* The counterpart of {@link toKeyScale}, and the one to prefer: both read the
|
|
150
|
+
* same shapes, but this one keeps what it read. A caller that genuinely wants
|
|
151
|
+
* only the pitch classes asks for them with {@link scaleOf}, which says so at
|
|
152
|
+
* the place it happens.
|
|
153
|
+
*
|
|
154
|
+
* What the value does not carry is derived rather than dropped: a bare scale is
|
|
155
|
+
* spelled by {@link spelledKeyOf}, the same reading the rest of the library
|
|
156
|
+
* uses, and its form is read from its mask. A key that carries a spelled tonic
|
|
157
|
+
* keeps that one — the caller's spelling outranks any the library would pick.
|
|
158
|
+
* A name carries one too, and it is kept: `'Ab minor'` resolves to an A flat
|
|
159
|
+
* minor rather than being reduced to pitch classes and spelled back as the G#
|
|
160
|
+
* minor those read best as.
|
|
161
|
+
*
|
|
162
|
+
* What it carries is checked rather than trusted. Accepting a wide range of
|
|
163
|
+
* shapes is not the same as accepting whatever those shapes hold, and a key
|
|
164
|
+
* whose tonic or form contradicts its own scale is refused here in the words
|
|
165
|
+
* `Key.of` refuses it — the two APIs answer the same input alike, and the
|
|
166
|
+
* refusal reaches every entry point built on this one.
|
|
167
|
+
*
|
|
168
|
+
* @param value A key name, a plain key/scale, a resolved key, or a value whose
|
|
169
|
+
* `toJSON` returns one of those.
|
|
170
|
+
* @returns The key, whole.
|
|
171
|
+
* @throws If the value names no key, its mask is out of range or excludes its
|
|
172
|
+
* own root, its tonic spells a pitch class its scale is not rooted on, or its
|
|
173
|
+
* form is not one that mask holds.
|
|
174
|
+
* @example
|
|
175
|
+
* ```ts
|
|
176
|
+
* import { formatNote, resolveKey } from '@libraz/libcantus';
|
|
177
|
+
* formatNote(resolveKey('Ab minor').tonic); // 'Ab'
|
|
178
|
+
* resolveKey('C major').tonic.letter; // 0
|
|
179
|
+
* ```
|
|
180
|
+
* @category Scales
|
|
181
|
+
*/
|
|
182
|
+
declare function resolveKey(value: KeyLike): ResolvedKey;
|
|
183
|
+
/**
|
|
184
|
+
* The pitch classes of a key, with its spelling and form deliberately dropped.
|
|
185
|
+
*
|
|
186
|
+
* Named so that dropping them is something a reader can see. A layer that
|
|
187
|
+
* reduces a key silently is where an Ab minor becomes a G# minor, and the only
|
|
188
|
+
* way to keep finding those is to make the reduction say its own name.
|
|
189
|
+
*
|
|
190
|
+
* @param key The key to read.
|
|
191
|
+
* @returns Its pitch classes alone.
|
|
192
|
+
* @category Scales
|
|
193
|
+
*/
|
|
194
|
+
declare function scaleOf(key: ResolvedKey): KeyScale;
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Build a `KeyScale` for a major key on the given root pitch class.
|
|
198
|
+
*
|
|
199
|
+
* @example
|
|
200
|
+
* ```ts
|
|
201
|
+
* import { majorKey } from '@libraz/libcantus';
|
|
202
|
+
* const cMajor = majorKey(0); // C major: { rootPc: 0, modeMask12: MAJOR_MASK }
|
|
203
|
+
* ```
|
|
204
|
+
*
|
|
205
|
+
* @category Scales
|
|
206
|
+
*/
|
|
207
|
+
declare function majorKey(rootPc: number): SpelledKeyScale;
|
|
208
|
+
/**
|
|
209
|
+
* Build a `KeyScale` for a natural-minor key on the given root pitch class.
|
|
210
|
+
*
|
|
211
|
+
* @example
|
|
212
|
+
* ```ts
|
|
213
|
+
* import { minorKey } from '@libraz/libcantus';
|
|
214
|
+
* const aMinor = minorKey(9); // A natural minor: { rootPc: 9, modeMask12: NATURAL_MINOR_MASK }
|
|
215
|
+
* ```
|
|
216
|
+
*
|
|
217
|
+
* @category Scales
|
|
218
|
+
*/
|
|
219
|
+
declare function minorKey(rootPc: number): SpelledKeyScale;
|
|
220
|
+
/**
|
|
221
|
+
* Build a `KeyScale` from a named scale (see {@link NAMED_SCALES}).
|
|
222
|
+
*
|
|
223
|
+
* @param name The scale name, e.g. `'dorian'` or `'harmonicMinor'`.
|
|
224
|
+
* @param rootPc The root pitch class.
|
|
225
|
+
* @returns The key/scale.
|
|
226
|
+
* @throws If the name is not a known scale.
|
|
227
|
+
*
|
|
228
|
+
* @example
|
|
229
|
+
* ```ts
|
|
230
|
+
* import { scaleByName } from '@libraz/libcantus';
|
|
231
|
+
* const dDorian = scaleByName('dorian', 2); // D Dorian, rootPc 2
|
|
232
|
+
* ```
|
|
233
|
+
*
|
|
234
|
+
* @category Scales
|
|
235
|
+
*/
|
|
236
|
+
declare function scaleByName(name: ScaleNameInput, rootPc: number): SpelledKeyScale;
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* Read a key name, reporting failure instead of throwing it.
|
|
240
|
+
*
|
|
241
|
+
* The scale-word form is tried first, because a name ending in a mode word —
|
|
242
|
+
* `'D harmonic minor'` — would otherwise be read as the plain minor key that
|
|
243
|
+
* word names and lose the scale it was written with. It is English-only, so a
|
|
244
|
+
* name asked for in another notation system goes straight to the key-name
|
|
245
|
+
* parser, which reads that system.
|
|
246
|
+
*
|
|
247
|
+
* @param text The key name.
|
|
248
|
+
* @param opts `system` reads the name in that notation system instead of
|
|
249
|
+
* detecting it.
|
|
250
|
+
* @returns The key the name denotes, or the error explaining why the text is
|
|
251
|
+
* not one.
|
|
252
|
+
* @example
|
|
253
|
+
* ```ts
|
|
254
|
+
* import { tryResolveKeyName } from '@libraz/libcantus';
|
|
255
|
+
* const result = tryResolveKeyName('D dorian');
|
|
256
|
+
* result.ok ? result.value.variant : result.error.message; // 'modal'
|
|
257
|
+
* ```
|
|
258
|
+
* @category Scales
|
|
259
|
+
*/
|
|
260
|
+
declare function tryResolveKeyName(text: string, opts?: NoteNameOptions): ParseResult<ResolvedKey>;
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Shared interval reading for the counterpoint rules.
|
|
264
|
+
*
|
|
265
|
+
* The predicates, the species checker and the independence metric all need the
|
|
266
|
+
* same two conversions — a pitch argument to a sounding pitch, and a spelled
|
|
267
|
+
* interval to its consonance class — and importing them from one another would
|
|
268
|
+
* make the module graph circular.
|
|
269
|
+
*/
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* Classify a spelled interval by consonance, the way a counterpoint exercise
|
|
273
|
+
* reads it.
|
|
274
|
+
*
|
|
275
|
+
* The spelling decides, not the semitone count: a diminished fourth is a
|
|
276
|
+
* dissonance though it sounds like a major third, and an augmented fifth is a
|
|
277
|
+
* dissonance though it sounds like a minor sixth. Only the perfect unison, fifth
|
|
278
|
+
* and octave and the major and minor thirds and sixths are consonant. The
|
|
279
|
+
* perfect fourth is context-dependent exactly as in {@link classifyInterval}.
|
|
280
|
+
*
|
|
281
|
+
* @param interval The spelled interval between the two voices.
|
|
282
|
+
* @param twoVoice When true, the perfect fourth counts as a dissonance.
|
|
283
|
+
* @returns The counterpoint quality of the interval.
|
|
284
|
+
* @example
|
|
285
|
+
* ```ts
|
|
286
|
+
* import { classifySpelledInterval, ConsonanceClass, parseInterval } from '@libraz/libcantus';
|
|
287
|
+
* classifySpelledInterval(parseInterval('d4')); // ConsonanceClass.Dissonance
|
|
288
|
+
* classifySpelledInterval(parseInterval('M3')); // ConsonanceClass.ImperfectConsonance
|
|
289
|
+
* ```
|
|
290
|
+
* @category Voicing & Counterpoint
|
|
291
|
+
*/
|
|
292
|
+
declare function classifySpelledInterval(interval: SpelledInterval, twoVoice?: boolean): ConsonanceClass;
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* Counterpoint predicates: each judges one pair of voices at one moment.
|
|
296
|
+
*
|
|
297
|
+
* Every predicate reads spelled notes, because spelling is what decides two of
|
|
298
|
+
* these rules. An augmented second and a minor third span the same three
|
|
299
|
+
* semitones, and a diminished fourth sounds like a major third; the first is a
|
|
300
|
+
* forbidden melodic leap and the second a vertical dissonance, and neither can
|
|
301
|
+
* be seen in a MIDI integer. {@link createsVerticalDissonance} and
|
|
302
|
+
* {@link isForbiddenMelodicLeap} therefore answer the spelled question when
|
|
303
|
+
* given spelled notes, and the sounding question — all a bare pitch can support
|
|
304
|
+
* — when given integers. {@link isAugmentedMelodicInterval} asks a question that
|
|
305
|
+
* has no sounding half at all, so its integer form answers false rather than
|
|
306
|
+
* refusing the call: every predicate here takes either form, and the ones that
|
|
307
|
+
* need spelling say so by degrading.
|
|
308
|
+
*
|
|
309
|
+
* The remaining rules compare registers or perfect classes, which spelling
|
|
310
|
+
* cannot change: a parallel fifth is a parallel fifth however the two voices are
|
|
311
|
+
* written. Those keep their integer form as an equal partner.
|
|
312
|
+
*/
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* The readings {@link createsHiddenParallelPerfect} judges an approach by.
|
|
316
|
+
*
|
|
317
|
+
* Named once so the three places the choice is spelled — the two overloads and
|
|
318
|
+
* the implementation — cannot fall out of step with the check that a caller's
|
|
319
|
+
* value is one of them.
|
|
320
|
+
*/
|
|
321
|
+
declare const HIDDEN_PARALLEL_READINGS: readonly ["fourPart", "twoVoice"];
|
|
322
|
+
/**
|
|
323
|
+
* Which reading of hidden parallels an approach is judged by.
|
|
324
|
+
*
|
|
325
|
+
* @category Voicing & Counterpoint
|
|
326
|
+
*/
|
|
327
|
+
type HiddenParallelReading = (typeof HIDDEN_PARALLEL_READINGS)[number];
|
|
328
|
+
/**
|
|
329
|
+
* Whether an upper voice has crossed below a lower voice.
|
|
330
|
+
*
|
|
331
|
+
* @param upper The nominally higher voice.
|
|
332
|
+
* @param lower The nominally lower voice.
|
|
333
|
+
* @returns True when the upper voice sits below the lower voice.
|
|
334
|
+
* @category Voicing & Counterpoint
|
|
335
|
+
*/
|
|
336
|
+
declare function createsVoiceCrossing(upper: Note, lower: Note): boolean;
|
|
337
|
+
declare function createsVoiceCrossing(upper: number, lower: number): boolean;
|
|
338
|
+
/**
|
|
339
|
+
* Whether two simultaneous voices form a dissonance.
|
|
340
|
+
*
|
|
341
|
+
* Given spelled notes the spelling decides, so a diminished fourth reads as the
|
|
342
|
+
* dissonance it is. Given MIDI integers only the sounding interval is available,
|
|
343
|
+
* which cannot tell that fourth from a major third; use the spelled form
|
|
344
|
+
* wherever the exercise is written in notes.
|
|
345
|
+
*
|
|
346
|
+
* @param a First voice.
|
|
347
|
+
* @param b Second voice.
|
|
348
|
+
* @param twoVoice When true, the perfect fourth counts as dissonant.
|
|
349
|
+
* @returns True when the vertical interval is dissonant.
|
|
350
|
+
* @example
|
|
351
|
+
* ```ts
|
|
352
|
+
* import { createsVerticalDissonance, parseNote } from '@libraz/libcantus';
|
|
353
|
+
* createsVerticalDissonance(parseNote('Fb4'), parseNote('C4'), true); // true — d4
|
|
354
|
+
* createsVerticalDissonance(64, 60, true); // false — the same pitches read as a major third
|
|
355
|
+
* ```
|
|
356
|
+
* @category Voicing & Counterpoint
|
|
357
|
+
*/
|
|
358
|
+
declare function createsVerticalDissonance(a: Note, b: Note, twoVoice: boolean): boolean;
|
|
359
|
+
declare function createsVerticalDissonance(a: number, b: number, twoVoice: boolean): boolean;
|
|
360
|
+
/**
|
|
361
|
+
* Whether a melodic move is a forbidden leap.
|
|
362
|
+
*
|
|
363
|
+
* Forbidden are the seventh in either quality, any leap wider than an octave,
|
|
364
|
+
* and — where the spelling is known — every augmented and diminished interval,
|
|
365
|
+
* the augmented second of the harmonic minor among them. Given MIDI integers the
|
|
366
|
+
* tritone is still caught, since it is forbidden under either spelling, but an
|
|
367
|
+
* augmented second is indistinguishable from a minor third and passes.
|
|
368
|
+
*
|
|
369
|
+
* The raw distance is used for the octave check, so a compound leap is not
|
|
370
|
+
* reduced to its simple class first.
|
|
371
|
+
*
|
|
372
|
+
* @param prev Starting note.
|
|
373
|
+
* @param cur Ending note.
|
|
374
|
+
* @returns True when the leap is forbidden in strict counterpoint.
|
|
375
|
+
* @example
|
|
376
|
+
* ```ts
|
|
377
|
+
* import { isForbiddenMelodicLeap, parseNote } from '@libraz/libcantus';
|
|
378
|
+
* isForbiddenMelodicLeap(parseNote('Ab4'), parseNote('B4')); // true — augmented second
|
|
379
|
+
* isForbiddenMelodicLeap(68, 71); // false — the same pitches read as a minor third
|
|
380
|
+
* ```
|
|
381
|
+
* @category Voicing & Counterpoint
|
|
382
|
+
*/
|
|
383
|
+
declare function isForbiddenMelodicLeap(prev: Note, cur: Note): boolean;
|
|
384
|
+
declare function isForbiddenMelodicLeap(prev: number, cur: number): boolean;
|
|
385
|
+
/**
|
|
386
|
+
* Whether a voice moves by an augmented interval — the melodic step no
|
|
387
|
+
* sixteenth-century line takes, and the one a MIDI integer cannot show.
|
|
388
|
+
*
|
|
389
|
+
* The augmented unison is excluded: raising or lowering the note a voice already
|
|
390
|
+
* holds is a chromatic inflection, not a leap.
|
|
391
|
+
*
|
|
392
|
+
* Every augmented interval sounds like a plain one — the augmented second like a
|
|
393
|
+
* minor third, the augmented fourth like a diminished fifth — so MIDI integers
|
|
394
|
+
* carry nothing this rule can read, and the numeric form always answers false.
|
|
395
|
+
* It exists so a host can run the whole predicate set over a bare pitch pair;
|
|
396
|
+
* take the spelled form wherever the exercise is written in notes.
|
|
397
|
+
*
|
|
398
|
+
* @param prev Starting note.
|
|
399
|
+
* @param cur Ending note.
|
|
400
|
+
* @returns True when the move spans an augmented second or wider.
|
|
401
|
+
* @example
|
|
402
|
+
* ```ts
|
|
403
|
+
* import { isAugmentedMelodicInterval, parseNote } from '@libraz/libcantus';
|
|
404
|
+
* isAugmentedMelodicInterval(parseNote('Ab4'), parseNote('B4')); // true — A2 in C minor
|
|
405
|
+
* isAugmentedMelodicInterval(parseNote('A4'), parseNote('C5')); // false — m3
|
|
406
|
+
* isAugmentedMelodicInterval(68, 71); // false — the same pitches carry no spelling
|
|
407
|
+
* ```
|
|
408
|
+
* @category Voicing & Counterpoint
|
|
409
|
+
*/
|
|
410
|
+
declare function isAugmentedMelodicInterval(prev: Note, cur: Note): boolean;
|
|
411
|
+
declare function isAugmentedMelodicInterval(prev: number, cur: number): boolean;
|
|
412
|
+
/**
|
|
413
|
+
* Whether two voices move into consecutive perfect intervals of the same kind
|
|
414
|
+
* (fifth-to-fifth, octave-to-octave, unison-to-unison).
|
|
415
|
+
*
|
|
416
|
+
* Both true parallels (similar motion) and anti-parallels — the same perfect
|
|
417
|
+
* class reached by contrary motion, e.g. octave to octave with the voices moving
|
|
418
|
+
* in opposite directions — are flagged, as both are forbidden in strict two-voice
|
|
419
|
+
* counterpoint. The rule requires that both voices actually move: oblique motion
|
|
420
|
+
* (either voice stationary) and the no-change case (identical pitches) are excluded.
|
|
421
|
+
*
|
|
422
|
+
* A fifth expanding to a twelfth counts (same perfect class); a fifth moving to
|
|
423
|
+
* an octave does not (different perfect kinds — the direct/hidden case owned by
|
|
424
|
+
* {@link createsHiddenParallelPerfect}).
|
|
425
|
+
*
|
|
426
|
+
* The perfect classes are what they sound like under any spelling, so spelled
|
|
427
|
+
* notes and MIDI integers give the same answer here.
|
|
428
|
+
*
|
|
429
|
+
* @category Voicing & Counterpoint
|
|
430
|
+
*/
|
|
431
|
+
declare function createsParallelPerfect(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
|
|
432
|
+
declare function createsParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
|
|
433
|
+
/**
|
|
434
|
+
* Whether two voices move in consecutive parallel octaves (or unisons) by
|
|
435
|
+
* similar motion.
|
|
436
|
+
*
|
|
437
|
+
* This is a strict subset of {@link createsParallelPerfect}: a similar-motion
|
|
438
|
+
* octave-to-octave is the perfect-class-zero case that predicate already flags
|
|
439
|
+
* (and it additionally catches the contrary-motion anti-parallel). Callers that
|
|
440
|
+
* tally parallel violations should therefore use {@link createsParallelPerfect}
|
|
441
|
+
* alone to avoid double counting; this predicate remains for callers wanting a
|
|
442
|
+
* dedicated similar-motion octave test.
|
|
443
|
+
*
|
|
444
|
+
* @category Voicing & Counterpoint
|
|
445
|
+
*/
|
|
446
|
+
declare function createsParallelOctave(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
|
|
447
|
+
declare function createsParallelOctave(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
|
|
448
|
+
/**
|
|
449
|
+
* Whether two voices move in consecutive parallel unisons — both landing on the
|
|
450
|
+
* same pitch, having shared a pitch on the previous move.
|
|
451
|
+
*
|
|
452
|
+
* @category Voicing & Counterpoint
|
|
453
|
+
*/
|
|
454
|
+
declare function createsParallelUnison(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
|
|
455
|
+
declare function createsParallelUnison(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
|
|
456
|
+
/**
|
|
457
|
+
* Whether two voices reach a perfect interval by similar motion from an
|
|
458
|
+
* imperfect one (a hidden/direct fifth or octave).
|
|
459
|
+
*
|
|
460
|
+
* How strictly the approach is judged is the caller's to say, because the two
|
|
461
|
+
* textures do not agree about it:
|
|
462
|
+
*
|
|
463
|
+
* - `fourPart` (the default) applies the step exception of the chorale — the
|
|
464
|
+
* approach is allowed when the upper of the two voices moves by step, so only
|
|
465
|
+
* leaps into the perfect interval are flagged. That exception is written for
|
|
466
|
+
* the outer voices of a four-part texture, where the other two cover the
|
|
467
|
+
* arrival.
|
|
468
|
+
* - `twoVoice` exempts no approach. With nothing between them, two voices
|
|
469
|
+
* moving the same way into a perfect fifth or octave expose it however the
|
|
470
|
+
* upper one got there, and strict sixteenth-century writing forbids it
|
|
471
|
+
* outright.
|
|
472
|
+
*
|
|
473
|
+
* @param strictness Which reading to judge the approach by.
|
|
474
|
+
* @category Voicing & Counterpoint
|
|
475
|
+
*/
|
|
476
|
+
declare function createsHiddenParallelPerfect(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note, strictness?: HiddenParallelReading): boolean;
|
|
477
|
+
declare function createsHiddenParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number, strictness?: HiddenParallelReading): boolean;
|
|
478
|
+
/**
|
|
479
|
+
* Whether two voices arrive at a perfect octave or unison by contrary motion
|
|
480
|
+
* with the upper voice leaping down — the *ottava battuta* the sixteenth-century
|
|
481
|
+
* theorists forbid.
|
|
482
|
+
*
|
|
483
|
+
* The stepwise arrival is allowed, as is the same octave reached with the upper
|
|
484
|
+
* voice rising, so only the downward leap into the perfect class is flagged.
|
|
485
|
+
* Arriving at a perfect class the voices were already sitting on (e.g. octave
|
|
486
|
+
* to octave by contrary motion) is the anti-parallel case owned by
|
|
487
|
+
* {@link createsParallelPerfect}; battuta is reserved for a perfect class that
|
|
488
|
+
* was not already there.
|
|
489
|
+
*
|
|
490
|
+
* @category Voicing & Counterpoint
|
|
491
|
+
*/
|
|
492
|
+
declare function createsBattuta(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
|
|
493
|
+
declare function createsBattuta(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
|
|
494
|
+
/**
|
|
495
|
+
* Whether two voices overlap: the upper voice descends below where the lower
|
|
496
|
+
* voice just was, or the lower voice rises above where the upper voice just was.
|
|
497
|
+
* Distinct from a simultaneous voice crossing.
|
|
498
|
+
*
|
|
499
|
+
* @param upperPrev Previous note of the upper voice.
|
|
500
|
+
* @param upperCur Current note of the upper voice.
|
|
501
|
+
* @param lowerPrev Previous note of the lower voice.
|
|
502
|
+
* @param lowerCur Current note of the lower voice.
|
|
503
|
+
* @category Voicing & Counterpoint
|
|
504
|
+
*/
|
|
505
|
+
declare function createsVoiceOverlap(upperPrev: Note, upperCur: Note, lowerPrev: Note, lowerCur: Note): boolean;
|
|
506
|
+
declare function createsVoiceOverlap(upperPrev: number, upperCur: number, lowerPrev: number, lowerCur: number): boolean;
|
|
507
|
+
/**
|
|
508
|
+
* Whether two adjacent upper voices are spaced more than a maximum apart
|
|
509
|
+
* (commonly an octave). Bass-to-tenor spacing is conventionally exempt, so this
|
|
510
|
+
* is meant for the upper voice pairs.
|
|
511
|
+
*
|
|
512
|
+
* @param upper The higher voice.
|
|
513
|
+
* @param lower The lower voice.
|
|
514
|
+
* @param maxSemitones Maximum allowed spacing in semitones (default an octave).
|
|
515
|
+
* @category Voicing & Counterpoint
|
|
516
|
+
*/
|
|
517
|
+
declare function exceedsSpacing(upper: Note, lower: Note, maxSemitones?: number): boolean;
|
|
518
|
+
declare function exceedsSpacing(upper: number, lower: number, maxSemitones?: number): boolean;
|
|
519
|
+
/**
|
|
520
|
+
* Whether a leading tone resolves correctly upward to the tonic.
|
|
521
|
+
*
|
|
522
|
+
* @param prev The leading-tone note.
|
|
523
|
+
* @param cur The following note.
|
|
524
|
+
* @param key Key context supplying the tonic.
|
|
525
|
+
* @returns True when `prev` is the leading tone and `cur` is the tonic a step above.
|
|
526
|
+
* @category Voicing & Counterpoint
|
|
527
|
+
*/
|
|
528
|
+
declare function isLeadingToneResolution(prev: Note, cur: Note, key: KeyLike): boolean;
|
|
529
|
+
declare function isLeadingToneResolution(prev: number, cur: number, key: KeyLike): boolean;
|
|
530
|
+
|
|
531
|
+
/**
|
|
532
|
+
* Total voice-leading cost between two voicings: the sum of absolute semitone
|
|
533
|
+
* motion across voices, and nothing besides. The rules the search also weighs —
|
|
534
|
+
* parallels, hidden perfects, unresolved tendency tones — are judged and
|
|
535
|
+
* reported by {@link checkPartWriting}, so measuring distance stays a
|
|
536
|
+
* measurement. The arrays must be the same length; when they differ the
|
|
537
|
+
* voicings are not comparable and the cost is `Infinity`.
|
|
538
|
+
*
|
|
539
|
+
* @param from The previous voicing, one MIDI pitch per voice.
|
|
540
|
+
* @param to The next voicing, one MIDI pitch per voice.
|
|
541
|
+
* @returns The summed absolute motion, or `Infinity` when lengths differ.
|
|
542
|
+
* @category Voicing & Counterpoint
|
|
543
|
+
*/
|
|
544
|
+
declare function voiceLeadingCost(from: number[], to: number[]): number;
|
|
545
|
+
/**
|
|
546
|
+
* Voice a single chord to follow smoothly from an arbitrary current voicing.
|
|
547
|
+
*
|
|
548
|
+
* Candidate voicings of `chord` are enumerated within ranges taken from `opts`,
|
|
549
|
+
* or — when neither `voices` nor `ranges` is given — from a one-octave window
|
|
550
|
+
* around each pitch of `current` (so the result matches `current`'s voice
|
|
551
|
+
* count). Each candidate is scored by structural quality, voice-leading motion
|
|
552
|
+
* from `current`, and a large penalty per counterpoint violation; the lowest
|
|
553
|
+
* scoring candidate is returned, ascending.
|
|
554
|
+
*
|
|
555
|
+
* The rules read from the chord being left — the resolution of a chordal
|
|
556
|
+
* seventh, the resolution of a leading tone, and the cross relation between the
|
|
557
|
+
* two chords — are scored only when `opts.previousChord` names it: what a
|
|
558
|
+
* voicing is written on cannot be read back from the pitches it holds. An
|
|
559
|
+
* editor moving from one chord to the next has that chord, and passing it is
|
|
560
|
+
* what keeps this generator and {@link checkPartWriting} agreeing about the
|
|
561
|
+
* pair.
|
|
562
|
+
*
|
|
563
|
+
* @param current The current voicing to lead from, ascending (index 0 = lowest).
|
|
564
|
+
* @param chord The next chord to voice, as a chord symbol, chord data, or a
|
|
565
|
+
* `Chord`.
|
|
566
|
+
* @param opts Voicing options; when omitted, ranges follow `current`'s span.
|
|
567
|
+
* @returns The chosen voicing, ascending with one MIDI pitch per voice.
|
|
568
|
+
* @throws If `current` is empty or holds a non-finite pitch while the ranges
|
|
569
|
+
* are derived from it, if it asks for more voices than the search will take,
|
|
570
|
+
* or if no voicing fits the ranges.
|
|
571
|
+
* @category Voicing & Counterpoint
|
|
572
|
+
*/
|
|
573
|
+
declare function nextVoicing(current: number[], chord: ChordLike, opts?: VoicingOptions): number[];
|
|
574
|
+
|
|
575
|
+
/**
|
|
576
|
+
* Figured bass: read a bass note and its figures as the chord they name.
|
|
577
|
+
*
|
|
578
|
+
* The figures are intervals above the bass, and every interval a figure does
|
|
579
|
+
* not alter is the one the key's own scale gives. That is the whole rule of the
|
|
580
|
+
* notation, and the reason a realization needs the key: the same `6` names a
|
|
581
|
+
* major triad over one degree of C major and a diminished one over another.
|
|
582
|
+
*
|
|
583
|
+
* The bass arrives spelled, so the intervals above it are spelled too. The
|
|
584
|
+
* third above a G in C minor is the Bb the signature gives, and the accidental
|
|
585
|
+
* that changes it is the one a score prints in front of that note: the leading
|
|
586
|
+
* tone there is a B natural, so the figure is `n`. That is the whole convention
|
|
587
|
+
* for accidentals here — a sign on a figure names its note exactly as it does on
|
|
588
|
+
* the staff — and it is what makes the figures of a real exercise readable as
|
|
589
|
+
* written. The crossed or slashed figure, typed `+`, is the one sign that raises
|
|
590
|
+
* instead of naming.
|
|
591
|
+
*/
|
|
592
|
+
|
|
593
|
+
/**
|
|
594
|
+
* A figure that moves over a held bass, such as the `4-3` suspension.
|
|
595
|
+
*
|
|
596
|
+
* @category Functional Harmony
|
|
597
|
+
*/
|
|
598
|
+
type FiguredBassSuspension = {
|
|
599
|
+
/** The interval above the bass that sounds first: the suspended note. */
|
|
600
|
+
from: number;
|
|
601
|
+
/** The interval it moves to, which is the one the chord contains. */
|
|
602
|
+
to: number;
|
|
603
|
+
/** The suspended note, spelled. */
|
|
604
|
+
note: Note;
|
|
605
|
+
/** The note it moves to, spelled. */
|
|
606
|
+
resolution: Note;
|
|
607
|
+
};
|
|
608
|
+
/**
|
|
609
|
+
* Everything a figured bass states: the chord, its spelled notes, and any
|
|
610
|
+
* figure that moves.
|
|
611
|
+
*
|
|
612
|
+
* @category Functional Harmony
|
|
613
|
+
*/
|
|
614
|
+
type FiguredBassRealization = {
|
|
615
|
+
/**
|
|
616
|
+
* The chord the figures name, carrying the given bass as its `bassPc` and
|
|
617
|
+
* the letter spellings of its root and bass as enharmonic hints.
|
|
618
|
+
*/
|
|
619
|
+
chord: Chord;
|
|
620
|
+
/**
|
|
621
|
+
* The spelled notes, bass first and then each figured interval in ascending
|
|
622
|
+
* order. They carry no octave: figures fix the intervals above the bass, not
|
|
623
|
+
* the register the upper voices take them in.
|
|
624
|
+
*/
|
|
625
|
+
notes: Note[];
|
|
626
|
+
/**
|
|
627
|
+
* Every moving figure, in written order, or an empty array for a static one.
|
|
628
|
+
* The chord above is the harmony these resolve into.
|
|
629
|
+
*/
|
|
630
|
+
suspensions: FiguredBassSuspension[];
|
|
631
|
+
};
|
|
632
|
+
/**
|
|
633
|
+
* Read a figured bass in full: the chord, its spelled notes, and its
|
|
634
|
+
* suspensions.
|
|
635
|
+
*
|
|
636
|
+
* The figure grammar, in the forms this accepts:
|
|
637
|
+
*
|
|
638
|
+
* - Nothing at all, `5`, `3` or `53` — the root-position triad.
|
|
639
|
+
* - `6` or `63` — the first-inversion triad; `64` — the second-inversion triad.
|
|
640
|
+
* - `7` — the root-position seventh chord; `65`, `43`, and `42` (also written
|
|
641
|
+
* `2`) — its first, second, and third inversions. The full stacks `753`,
|
|
642
|
+
* `653`, `643` and `642` name the same four chords.
|
|
643
|
+
* - Stacked figures may be written run together (`64`) or separated by a slash,
|
|
644
|
+
* a comma or a space (`6/4`), which is the same figure either way.
|
|
645
|
+
* - An accidental in front of a figure names that interval's note, exactly as
|
|
646
|
+
* the same sign does on the staff: `#6`, `b7`, `#43`, and `n3` for a note the
|
|
647
|
+
* signature would otherwise flatten. `##` and `bb` name the double
|
|
648
|
+
* accidentals. An accidental with no figure applies to the third above the
|
|
649
|
+
* bass, so a lone `n` over the dominant of C minor names its leading tone. The
|
|
650
|
+
* Unicode accidentals are accepted alongside the typed ones.
|
|
651
|
+
* - A slashed or crossed figure raises the interval the key gives by a semitone,
|
|
652
|
+
* whatever accidental that lands on, and is typed `+`. It is the one sign here
|
|
653
|
+
* that moves an interval rather than naming it, which is why the notation
|
|
654
|
+
* carries it beside the printed accidentals: `+3` over the dominant of C minor
|
|
655
|
+
* and `+3` over the dominant of A minor are each that key's leading tone,
|
|
656
|
+
* written `n3` and `#3` respectively.
|
|
657
|
+
* - A figure that moves is written with a hyphen: `4-3`, `9-8`, `7-6`, and any
|
|
658
|
+
* other pair. Each side may carry its own accidental, as `4-#3` does in a
|
|
659
|
+
* minor key. Moving figures may stand beside static ones (`5 4-3`).
|
|
660
|
+
*
|
|
661
|
+
* Every interval no accidental touches is the one the key's scale gives, which
|
|
662
|
+
* is why the key is required and why the same figure names different qualities
|
|
663
|
+
* over different degrees.
|
|
664
|
+
*
|
|
665
|
+
* A moving figure resolves into the chord: `4-3` over a G in C major returns
|
|
666
|
+
* the G major triad, and the suspended C is reported as a suspension rather
|
|
667
|
+
* than as a chord tone. A suspension is a melodic event over a single harmony —
|
|
668
|
+
* the sounding chord does not change when it resolves — so naming the
|
|
669
|
+
* resolution is the reading that answers "which chord is this", and the record
|
|
670
|
+
* of what was suspended is kept beside it rather than thrown away.
|
|
671
|
+
*
|
|
672
|
+
* @param bass The bass note, spelled: a note name, a MIDI number, note data, or
|
|
673
|
+
* a `Note`; its octave, if any, is not used.
|
|
674
|
+
* @param figures The figures written under the bass; empty for an unfigured
|
|
675
|
+
* note.
|
|
676
|
+
* @param key The prevailing key, which supplies every unaltered interval, as a
|
|
677
|
+
* key name, a key/scale, or a `Key`.
|
|
678
|
+
* @returns The chord, its spelled notes, and any suspensions.
|
|
679
|
+
* @throws If the figures are malformed or name no chord
|
|
680
|
+
* ({@link InvalidInputError}), if the key is not heptatonic
|
|
681
|
+
* ({@link InvalidInputError}), or if the figures sound a chord no
|
|
682
|
+
* {@link ChordQuality} names, such as an augmented sixth
|
|
683
|
+
* ({@link NoSolutionError}).
|
|
684
|
+
* @example
|
|
685
|
+
* ```ts
|
|
686
|
+
* import { figuredBassRealization, majorKey, noteNames, parseNote } from '@libraz/libcantus';
|
|
687
|
+
* const realized = figuredBassRealization(parseNote('G'), '4-3', majorKey(0));
|
|
688
|
+
* noteNames(realized.notes); // ['G', 'B', 'D']
|
|
689
|
+
* realized.suspensions[0]?.from; // 4 — the suspended C above the bass
|
|
690
|
+
* ```
|
|
691
|
+
* @category Functional Harmony
|
|
692
|
+
*/
|
|
693
|
+
declare function figuredBassRealization(bass: NoteLike, figures: string, key: KeyLike): FiguredBassRealization;
|
|
694
|
+
/**
|
|
695
|
+
* Realize a figured bass: the chord a bass note and its figures name in a key.
|
|
696
|
+
*
|
|
697
|
+
* The chord carries the given bass as its `bassPc`, so an inversion reads as
|
|
698
|
+
* one everywhere the library measures a bass against a root, and carries the
|
|
699
|
+
* letter spellings of its root and bass so the realization can be respelled
|
|
700
|
+
* without losing the accidentals the figures asked for.
|
|
701
|
+
*
|
|
702
|
+
* See {@link figuredBassRealization} for the figure grammar this accepts and
|
|
703
|
+
* for the spelled notes and suspensions it drops. A moving figure such as
|
|
704
|
+
* `4-3` returns the chord it resolves into.
|
|
705
|
+
*
|
|
706
|
+
* @param bass The bass note, spelled; its octave, if any, is not used.
|
|
707
|
+
* @param figures The figures written under the bass; empty for an unfigured
|
|
708
|
+
* note.
|
|
709
|
+
* @param key The prevailing key, which supplies every unaltered interval.
|
|
710
|
+
* @param bass The bass note, spelled: a note name, a MIDI number, note data, or
|
|
711
|
+
* a `Note`.
|
|
712
|
+
* @param figures The figures written under the bass.
|
|
713
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
714
|
+
* @returns The chord the figures name.
|
|
715
|
+
* @throws If the figures are malformed or name no chord
|
|
716
|
+
* ({@link InvalidInputError}), if the key is not heptatonic
|
|
717
|
+
* ({@link InvalidInputError}), or if the figures sound a chord no
|
|
718
|
+
* {@link ChordQuality} names ({@link NoSolutionError}).
|
|
719
|
+
* @example
|
|
720
|
+
* ```ts
|
|
721
|
+
* import { majorKey, minorKey, parseNote, realizeFiguredBass } from '@libraz/libcantus';
|
|
722
|
+
* realizeFiguredBass(parseNote('B'), '6', majorKey(0));
|
|
723
|
+
* // G major with B in the bass: { rootPc: 7, quality: 'maj', bassPc: 11, ... }
|
|
724
|
+
* realizeFiguredBass(parseNote('G'), 'n', minorKey(0));
|
|
725
|
+
* // G major in C minor: the leading tone is the B natural the score prints
|
|
726
|
+
* ```
|
|
727
|
+
* @category Functional Harmony
|
|
728
|
+
*/
|
|
729
|
+
declare function realizeFiguredBass(bass: NoteLike, figures: string, key: KeyLike): Chord;
|
|
730
|
+
/**
|
|
731
|
+
* Write a chord as the figures a bass would carry under it, in a key.
|
|
732
|
+
*
|
|
733
|
+
* The inverse of {@link realizeFiguredBass} for every chord the figure grammar
|
|
734
|
+
* reaches: the conventional abbreviation for the inversion (`6`, `64`, `7`,
|
|
735
|
+
* `65`, `43`, `42`, or nothing at all for a root-position triad), with an
|
|
736
|
+
* accidental on any interval the key does not already give. The accidental is
|
|
737
|
+
* the sign the score prints in front of that note, so the third of the dominant
|
|
738
|
+
* in C minor — a B natural under a signature carrying B flat — is written `n3`
|
|
739
|
+
* rather than as a raise from the flat the key gives. An altered interval the
|
|
740
|
+
* abbreviation would leave implied is written out, so the figure names the
|
|
741
|
+
* interval it lands on rather than the bare accidental a score puts under the
|
|
742
|
+
* bass — the figures this returns read back as the same chord.
|
|
743
|
+
*
|
|
744
|
+
* What this returns is read back before it is returned, so the two directions
|
|
745
|
+
* cannot disagree: a chord the digits would name only approximately has no
|
|
746
|
+
* figures rather than figures that fail to realize. What that excludes is a
|
|
747
|
+
* stack, not a family of chords — the Italian and German sixths are
|
|
748
|
+
* conventionally figured `#6` and `#6/5/3`, but their tones do not stack in
|
|
749
|
+
* thirds into any chord quality, so this reads no figures for them (and
|
|
750
|
+
* {@link realizeFiguredBass} raises {@link NoSolutionError} for those figures).
|
|
751
|
+
* That is a limit of the quality vocabulary, not of the notation. The French
|
|
752
|
+
* sixth stacks from its lowered supertonic and is written `#643`, which
|
|
753
|
+
* realizes back to the chord it was written from.
|
|
754
|
+
*
|
|
755
|
+
* @param chord The chord to figure, as a chord symbol, chord data, or a
|
|
756
|
+
* `Chord`; its `bassPc`, when present, is the bass the intervals are measured
|
|
757
|
+
* above.
|
|
758
|
+
* @param key The prevailing key, which decides which intervals need no
|
|
759
|
+
* accidental, as a key name, a key/scale, or a `Key`.
|
|
760
|
+
* @returns The figures, as {@link realizeFiguredBass} accepts them.
|
|
761
|
+
* @throws If the key is not heptatonic ({@link InvalidInputError}), or if no
|
|
762
|
+
* figure names the chord — its bass is not one of its tones, its tones do not
|
|
763
|
+
* stack in diatonic thirds above that bass, or it is an added-tone or
|
|
764
|
+
* extended chord the notation has no abbreviation for
|
|
765
|
+
* ({@link NoSolutionError}).
|
|
766
|
+
* @example
|
|
767
|
+
* ```ts
|
|
768
|
+
* import { figuredBassOf, majorKey, makeChord } from '@libraz/libcantus';
|
|
769
|
+
* figuredBassOf(makeChord(7, 'maj', 11), majorKey(0)); // '6' — G major over B
|
|
770
|
+
* figuredBassOf(makeChord(7, 'dom7', 2), majorKey(0)); // '43' — G7 over D
|
|
771
|
+
* ```
|
|
772
|
+
* @category Functional Harmony
|
|
773
|
+
*/
|
|
774
|
+
declare function figuredBassOf(chord: ChordLike, key: SpelledKeyLike): string;
|
|
775
|
+
|
|
776
|
+
/**
|
|
777
|
+
* Spelling: derive letter-name notes for scales and chords from a spelled tonic.
|
|
778
|
+
*
|
|
779
|
+
* The theory core works in pitch classes, which cannot choose between (say) a
|
|
780
|
+
* G# and an Ab. Given a spelled tonic, this module assigns diatonic letters to
|
|
781
|
+
* scale degrees and chord tones so a C major scale spells as C D E F G A B and
|
|
782
|
+
* A harmonic minor spells its seventh as G#.
|
|
783
|
+
*
|
|
784
|
+
* Every entry point takes the spelled tonic *of the key it spells*: a tonic
|
|
785
|
+
* sounding a pitch class other than `key.rootPc` is rejected rather than
|
|
786
|
+
* spelled, because the letters counted from it name no reading of the key.
|
|
787
|
+
*/
|
|
788
|
+
|
|
789
|
+
/**
|
|
790
|
+
* The musical evidence around a pitch, used to refine an enharmonic choice the
|
|
791
|
+
* key alone cannot make.
|
|
792
|
+
*
|
|
793
|
+
* Every field is optional and every field is only ever advisory: a context that
|
|
794
|
+
* says nothing about the pitch leaves its key spelling untouched.
|
|
795
|
+
*
|
|
796
|
+
* @category Pitch & Intervals
|
|
797
|
+
*/
|
|
798
|
+
type SpellingContext = {
|
|
799
|
+
/**
|
|
800
|
+
* The chord sounding under the pitch, when the caller holds it.
|
|
801
|
+
*
|
|
802
|
+
* A chord names its own tones better than its root alone can: it carries the
|
|
803
|
+
* degree it writes each tone as, so a pitch that is one of its tones is
|
|
804
|
+
* spelled exactly as {@link spellChord} spells it. Supersedes `chordRoot`,
|
|
805
|
+
* which stays for callers holding nothing but a root pitch class.
|
|
806
|
+
*/
|
|
807
|
+
chord?: Chord;
|
|
808
|
+
/** Root pitch class of the chord sounding under the pitch, when known. */
|
|
809
|
+
chordRoot?: number;
|
|
810
|
+
/** The pitch immediately before this one (MIDI pitch or bare pitch class). */
|
|
811
|
+
previous?: number;
|
|
812
|
+
/** The pitch immediately after this one (MIDI pitch or bare pitch class). */
|
|
813
|
+
next?: number;
|
|
814
|
+
};
|
|
815
|
+
/**
|
|
816
|
+
* Spell a single pitch class relative to a spelled tonic and key, optionally
|
|
817
|
+
* refined by the music around it.
|
|
818
|
+
*
|
|
819
|
+
* Without a context the key decides alone: the tonic spells as itself, each
|
|
820
|
+
* degree of a heptatonic key takes the next letter above the tonic, a gapped
|
|
821
|
+
* scale gives each of its own tones a letter wherever its pitch set allows one,
|
|
822
|
+
* and every other pitch class takes the conventional interval spelling above
|
|
823
|
+
* the tonic's letter, so a flat-side key keeps flat-side names.
|
|
824
|
+
*
|
|
825
|
+
* A context only ever refines a pitch class the key leaves ambiguous — one that
|
|
826
|
+
* is not a tone of `key`. Scale tones, and the tonic, keep their key spelling
|
|
827
|
+
* whatever the context says.
|
|
828
|
+
*
|
|
829
|
+
* The melodic rules read the two neighbours differently, because a chromatic
|
|
830
|
+
* note is an inflection of the note it came from but a leading tone into the
|
|
831
|
+
* note it goes to: `next` moves the letter, `previous` keeps it. For a chromatic
|
|
832
|
+
* pitch class the evidence is weighed in this order, and the first spelling
|
|
833
|
+
* within a double accidental wins:
|
|
834
|
+
*
|
|
835
|
+
* 1. The sounding chord, when `chordRoot` is given and the pitch is an
|
|
836
|
+
* unambiguous chord tone above it (root, third, fifth or seventh) — the third
|
|
837
|
+
* of a secondary dominant D7 in C major spells F#, not Gb.
|
|
838
|
+
* 2. Resolution: `next` a semitone above makes the pitch a leading tone into it,
|
|
839
|
+
* one letter below — the C# rising to D in D minor.
|
|
840
|
+
* 3. Approach: `previous` a semitone below inflects that note upward, keeping
|
|
841
|
+
* its letter, so a chromatic ascent spells with sharps — F F# G in C major.
|
|
842
|
+
* 4. Descent: `next` a semitone below puts the pitch one letter above it, so a
|
|
843
|
+
* falling chromatic line spells with flats — A Ab G in C major. Failing that,
|
|
844
|
+
* `previous` a semitone above inflects that note downward on its own letter,
|
|
845
|
+
* which spells the same line from the note before instead.
|
|
846
|
+
*
|
|
847
|
+
* If no rule applies, or every candidate would need more than a double
|
|
848
|
+
* accidental, the key spelling stands.
|
|
849
|
+
*
|
|
850
|
+
* @param pc The pitch class to spell.
|
|
851
|
+
* @param tonic The spelled tonic (its letter anchors the spelling), as a note
|
|
852
|
+
* name, a MIDI number, note data, or a `Note`.
|
|
853
|
+
* @param key The key/scale, as a key name, a key/scale, or a `Key`.
|
|
854
|
+
* @param context Optional surrounding evidence; an absent or empty context
|
|
855
|
+
* spells exactly as the key alone does.
|
|
856
|
+
* @returns The spelled note (without octave).
|
|
857
|
+
* @throws If `tonic` does not sound the key's root pitch class.
|
|
858
|
+
* @example
|
|
859
|
+
* ```ts
|
|
860
|
+
* import { spellPitchClass, formatNote, parseNote, majorKey } from '@libraz/libcantus';
|
|
861
|
+
* const c = parseNote('C');
|
|
862
|
+
* formatNote(spellPitchClass(6, c, majorKey(0))); // 'F#'
|
|
863
|
+
* // The third of D7, the secondary dominant of G.
|
|
864
|
+
* formatNote(spellPitchClass(6, 'C', 'C major', { chordRoot: 2 })); // 'F#'
|
|
865
|
+
* // A chromatic passing tone falling from G to F.
|
|
866
|
+
* formatNote(spellPitchClass(6, c, majorKey(0), { previous: 7, next: 5 })); // 'Gb'
|
|
867
|
+
* ```
|
|
868
|
+
* @category Pitch & Intervals
|
|
869
|
+
*/
|
|
870
|
+
declare function spellPitchClass(pc: number, tonic: NoteLike, key: KeyLike, context?: SpellingContext): Note;
|
|
871
|
+
/**
|
|
872
|
+
* Spell every pitch class of a scale, in ascending scale-degree order.
|
|
873
|
+
*
|
|
874
|
+
* Correct for heptatonic scales (each degree gets the next letter). A gapped
|
|
875
|
+
* scale gives each of its tones a letter of its own wherever its pitch set
|
|
876
|
+
* allows one — C miyako-bushi spells C Db F G Ab — and is spelled tone by tone,
|
|
877
|
+
* on the accidental side the scale leans towards, where it does not: the blues
|
|
878
|
+
* scale has to name one letter twice however it is read.
|
|
879
|
+
*
|
|
880
|
+
* @param tonic The spelled tonic, as a note name, a MIDI number, note data, or a
|
|
881
|
+
* `Note`.
|
|
882
|
+
* @param key The key/scale, as a key name, a key/scale, or a `Key` — the same
|
|
883
|
+
* forms its sibling spellers take.
|
|
884
|
+
* @returns Spelled notes, one per scale degree.
|
|
885
|
+
* @throws If `key` names no key, or if `tonic` does not sound the key's root
|
|
886
|
+
* pitch class.
|
|
887
|
+
* @example
|
|
888
|
+
* ```ts
|
|
889
|
+
* import { spellScale, noteNames, parseNote, majorKey } from '@libraz/libcantus';
|
|
890
|
+
* noteNames(spellScale(parseNote('C'), majorKey(0)));
|
|
891
|
+
* // ['C', 'D', 'E', 'F', 'G', 'A', 'B']
|
|
892
|
+
* ```
|
|
893
|
+
* @category Pitch & Intervals
|
|
894
|
+
*/
|
|
895
|
+
declare function spellScale(tonic: NoteLike, key: KeyLike): Note[];
|
|
896
|
+
/**
|
|
897
|
+
* Spell an arbitrary list of pitch classes relative to a key.
|
|
898
|
+
*
|
|
899
|
+
* @param pcs The pitch classes.
|
|
900
|
+
* @param tonic The spelled tonic, as a note name, a MIDI number, note data, or a
|
|
901
|
+
* `Note`.
|
|
902
|
+
* @param key The key/scale, as a key name, a key/scale, or a `Key`.
|
|
903
|
+
* @returns Spelled notes, in input order.
|
|
904
|
+
* @throws If `tonic` does not sound the key's root pitch class.
|
|
905
|
+
* @category Pitch & Intervals
|
|
906
|
+
*/
|
|
907
|
+
declare function spellPitchClasses(pcs: number[], tonic: NoteLike, key: KeyLike): Note[];
|
|
908
|
+
/**
|
|
909
|
+
* Spell chord tones from an already chosen root spelling.
|
|
910
|
+
*
|
|
911
|
+
* This is public for callers that already know the desired root spelling;
|
|
912
|
+
* {@link spellChord} instead derives that spelling from the chord and key.
|
|
913
|
+
*
|
|
914
|
+
* Letters follow the chord's own tone spellings when it carries a usable set,
|
|
915
|
+
* and otherwise the diatonic distance each interval implies in a stack of
|
|
916
|
+
* thirds. Accidentals are always recomputed from the sounding pitch class, so
|
|
917
|
+
* the tones name exactly the chord's own pitch classes either way.
|
|
918
|
+
*
|
|
919
|
+
* @param chord The chord whose tones are spelled.
|
|
920
|
+
* @param root The chosen root spelling, as a note name, a MIDI number, note
|
|
921
|
+
* data, or a `Note`.
|
|
922
|
+
*/
|
|
923
|
+
declare function spellChordFromRoot(chord: Chord, root: NoteLike): Note[];
|
|
924
|
+
/**
|
|
925
|
+
* Spell a chord's tones, in the chord's own (tertian) order, relative to a key.
|
|
926
|
+
*
|
|
927
|
+
* Diatonic chords spell exactly (e.g. G7 in C major -> G B D F). Chromatic chord
|
|
928
|
+
* tones take their conventional spelling; enharmonically ambiguous altered
|
|
929
|
+
* tensions may be spelled by the general convention rather than by chord
|
|
930
|
+
* function.
|
|
931
|
+
*
|
|
932
|
+
* A chord carrying its own tone spellings is spelled by them, since a chord
|
|
933
|
+
* whose letters do not follow from stacking thirds can say so no other way:
|
|
934
|
+
* that is what keeps the German sixth of C major on its F#, the note that
|
|
935
|
+
* resolves outward to the dominant, rather than the Gb a dominant seventh
|
|
936
|
+
* would put there.
|
|
937
|
+
*
|
|
938
|
+
* @param chord The chord.
|
|
939
|
+
* @param tonic The spelled tonic of the key, as a note name, a MIDI number,
|
|
940
|
+
* note data, or a `Note`.
|
|
941
|
+
* @param key The key/scale, as a key name, a key/scale, or a `Key`.
|
|
942
|
+
* @returns Spelled chord tones, root first.
|
|
943
|
+
* @throws If `tonic` does not sound the key's root pitch class.
|
|
944
|
+
* @example
|
|
945
|
+
* ```ts
|
|
946
|
+
* import { spellChord, noteNames, parseNote, majorKey, makeChord } from '@libraz/libcantus';
|
|
947
|
+
* // G7 in C major
|
|
948
|
+
* noteNames(spellChord(makeChord(7, 'dom7'), parseNote('C'), majorKey(0)));
|
|
949
|
+
* // ['G', 'B', 'D', 'F']
|
|
950
|
+
* ```
|
|
951
|
+
* @category Pitch & Intervals
|
|
952
|
+
*/
|
|
953
|
+
declare function spellChord(chord: Chord, tonic: NoteLike, key: KeyLike): Note[];
|
|
954
|
+
/**
|
|
955
|
+
* Spell a MIDI pitch relative to a key, keeping its octave.
|
|
956
|
+
*
|
|
957
|
+
* The octave-less sibling of this function, {@link spellPitchClass}, is enough
|
|
958
|
+
* for chord and scale spelling; this one is for naming actual sounding pitches
|
|
959
|
+
* (a generated line, an imported track) without losing the register.
|
|
960
|
+
*
|
|
961
|
+
* The octave is the one that reproduces `pitch` from the chosen spelling, so a
|
|
962
|
+
* context that changes the letter changes the octave with it: MIDI 60 spelled
|
|
963
|
+
* B# is B#3, not B#4.
|
|
964
|
+
*
|
|
965
|
+
* @param pitch The MIDI pitch; rounded to the nearest integer.
|
|
966
|
+
* @param tonic The spelled tonic of the key, as a note name, a MIDI number,
|
|
967
|
+
* note data, or a `Note`.
|
|
968
|
+
* @param key The key/scale, as a key name, a key/scale, or a `Key`.
|
|
969
|
+
* @param context Optional surrounding evidence, weighed exactly as
|
|
970
|
+
* {@link spellPitchClass} weighs it.
|
|
971
|
+
* @returns The spelled note, carrying the octave that reproduces `pitch`.
|
|
972
|
+
* @throws If `tonic` does not sound the key's root pitch class.
|
|
973
|
+
* @example
|
|
974
|
+
* ```ts
|
|
975
|
+
* import { spellPitch, formatNote, parseNote, majorKey } from '@libraz/libcantus';
|
|
976
|
+
* formatNote(spellPitch(70, parseNote('Eb'), majorKey(3))); // 'Bb4'
|
|
977
|
+
* ```
|
|
978
|
+
* @category Pitch & Intervals
|
|
979
|
+
*/
|
|
980
|
+
declare function spellPitch(pitch: number, tonic: NoteLike, key: KeyLike, context?: SpellingContext): Note;
|
|
981
|
+
/**
|
|
982
|
+
* Convenience: render spelled notes as letter-name strings.
|
|
983
|
+
*
|
|
984
|
+
* @param notes The notes, each a note name, a MIDI number, note data, or a
|
|
985
|
+
* `Note`.
|
|
986
|
+
* @returns Their formatted names.
|
|
987
|
+
* @category Pitch & Intervals
|
|
988
|
+
*/
|
|
989
|
+
declare function noteNames(notes: readonly NoteLike[]): string[];
|
|
990
|
+
|
|
991
|
+
export { Chord as ChordData, ChordLike, ConsonanceClass, KeyLike, KeyScale, Note as NoteData, NoteLike, NoteNameOptions, ParseResult, ResolvedKey, ScaleNameInput, SpelledInterval, SpelledKeyLike, SpelledKeyScale, VoicingOptions, classifySpelledInterval, createsBattuta, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, figuredBassOf, figuredBassRealization, isAugmentedMelodicInterval, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, minorKey, nearestScaleTone, nextVoicing, noteNames, pitchToScaleDegree, realizeFiguredBass, resolveKey, scaleByName, scaleLadderPitch, scaleLadderPosition, scaleOf, scaleTonesInDegreeOrder, shiftByScaleDegrees, spellChord, spellChordFromRoot, spellPitch, spellPitchClass, spellPitchClasses, spellScale, tryResolveKeyName, voiceLeadingCost };
|
|
992
|
+
export type { FiguredBassRealization, FiguredBassSuspension, HiddenParallelReading, ScaleLadderPosition, SpellingContext };
|