@libraz/libcantus-wasm 0.0.0-stage → 1.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/NOTICE +63 -0
- package/README.md +75 -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-6X5QS3NE.js +6941 -0
- package/dist/coerce-Cr9AZsTY.d.ts +1322 -0
- package/dist/core/index.d.ts +293 -0
- package/dist/core/index.js +224 -0
- package/dist/generate/index.d.ts +810 -0
- package/dist/generate/index.js +150 -0
- package/dist/index-C1dnzRkt.d.ts +2902 -0
- package/dist/index-C9MYbuKS.d.ts +804 -0
- package/dist/index-CBQLVwv_.d.ts +64 -0
- package/dist/index-COyI6W_w.d.ts +1363 -0
- package/dist/index-Cbs3SQe9.d.ts +665 -0
- package/dist/index-DInQqT8Q.d.ts +66 -0
- package/dist/index-wE8SecK5.d.ts +515 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +802 -0
- package/dist/masks-BDxvQO8b.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-kmJqJ3aO.d.ts +1508 -0
- package/dist/theory/index.d.ts +990 -0
- package/dist/theory/index.js +288 -0
- package/dist/types-DPPzRpc3.d.ts +2599 -0
- package/package.json +93 -4
|
@@ -0,0 +1,1363 @@
|
|
|
1
|
+
import { e as KeyScale, i as NoteLike, j as NoteNameOptions, P as ParseResult, g as Note, b as IntervalLike, S as SpelledInterval } from './index-C9MYbuKS.js';
|
|
2
|
+
import { n as ResolvedKey, K as KeyLike, c as ChordLike, b as Chord, r as SpelledKeyLike } from './coerce-Cr9AZsTY.js';
|
|
3
|
+
import { r as ScaleName, u as WorldScaleName, s as ScaleNameInput } from './masks-BDxvQO8b.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Which of the two modes a key signature is read in.
|
|
7
|
+
*
|
|
8
|
+
* A signature names two keys — three sharps is both A major and F# minor — so
|
|
9
|
+
* every entry point that turns a signature into a key, or that names the mode
|
|
10
|
+
* of a key relation, selects between them with this.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```ts
|
|
14
|
+
* import type { KeyMode } from '@libraz/libcantus';
|
|
15
|
+
* const mode: KeyMode = 'minor';
|
|
16
|
+
* ```
|
|
17
|
+
* @category Scales
|
|
18
|
+
*/
|
|
19
|
+
type KeyMode = 'major' | 'minor';
|
|
20
|
+
/**
|
|
21
|
+
* Whether a key is one that is actually written with a key signature.
|
|
22
|
+
*
|
|
23
|
+
* Each of the seven diatonic modes has a signature of its own, and the harmonic
|
|
24
|
+
* and melodic minor are the minor key with a degree or two raised: G# harmonic
|
|
25
|
+
* minor is written with G# minor's five sharps and an F## in front of the note,
|
|
26
|
+
* which is why it is spelled G# and not Ab. Every other scale only borrows the
|
|
27
|
+
* signature of its parallel major or minor as an approximation, so nothing
|
|
28
|
+
* about how it is written follows from that signature — and how such a scale is
|
|
29
|
+
* spelled has to be decided from the scale itself.
|
|
30
|
+
*
|
|
31
|
+
* @param key The key/scale.
|
|
32
|
+
* @returns True when the signature is the key's own rather than a stand-in.
|
|
33
|
+
*/
|
|
34
|
+
declare function isSignatureKey(key: KeyScale): boolean;
|
|
35
|
+
/**
|
|
36
|
+
* The key signature of a key, as a signed count of sharps (positive) or flats
|
|
37
|
+
* (negative) — the `fifths` value a notation format such as MusicXML writes.
|
|
38
|
+
*
|
|
39
|
+
* The tonic's letter and accidental place the key on the circle of fifths, and
|
|
40
|
+
* the mode moves it from there: lydian +1, major 0, mixolydian -1, dorian -2,
|
|
41
|
+
* natural minor -3, phrygian -4, locrian -5.
|
|
42
|
+
*
|
|
43
|
+
* A scale that is not a diatonic mode has no signature of its own, so it takes
|
|
44
|
+
* the signature of its parallel major or minor: a scale with a minor third and
|
|
45
|
+
* no major third counts as minor (-3), everything else as major (0). This is
|
|
46
|
+
* why A harmonic minor reports 0 — its G# is written as an accidental, not in
|
|
47
|
+
* the signature — and why A melodic minor reports 0 as well.
|
|
48
|
+
*
|
|
49
|
+
* The result is not clamped: a theoretical key such as Fb major reports -8.
|
|
50
|
+
* Clamp to ±7 if the consuming format cannot express more.
|
|
51
|
+
*
|
|
52
|
+
* @param tonic The spelled tonic, as a note name, note data, or a `Note`; its
|
|
53
|
+
* accidental is worth seven fifths.
|
|
54
|
+
* @param key The key/scale. This one stays a plain key/scale: it reads any
|
|
55
|
+
* 12-bit mask, including the tonic-less ones a key name cannot describe.
|
|
56
|
+
* @returns The signed number of sharps (positive) or flats (negative).
|
|
57
|
+
* @example
|
|
58
|
+
* ```ts
|
|
59
|
+
* import { keySignatureFifths, majorKey, minorKey, parseNote } from '@libraz/libcantus';
|
|
60
|
+
* keySignatureFifths(parseNote('Bb'), majorKey(10)); // -2
|
|
61
|
+
* keySignatureFifths('A', minorKey(9)); // 0
|
|
62
|
+
* ```
|
|
63
|
+
* @category Scales
|
|
64
|
+
*/
|
|
65
|
+
declare function keySignatureFifths(tonic: NoteLike, key: KeyLike): number;
|
|
66
|
+
/**
|
|
67
|
+
* The key a signature denotes: the inverse of {@link keySignatureFifths} for
|
|
68
|
+
* the two modes a signature is conventionally read in.
|
|
69
|
+
*
|
|
70
|
+
* A signature names two keys — three sharps is both A major and F# minor — so
|
|
71
|
+
* the mode decides which one is built. The tonic is spelled the way that key is
|
|
72
|
+
* written, including the theoretical keys past ±7 (nine sharps is D# major).
|
|
73
|
+
*
|
|
74
|
+
* @param fifths The signed number of sharps (positive) or flats (negative).
|
|
75
|
+
* @param mode Which of the signature's two keys to build; defaults to major.
|
|
76
|
+
* @returns The spelled tonic and the matching key/scale.
|
|
77
|
+
* @throws If `fifths` is not an integer in [-12, 12], or `mode` is not one of
|
|
78
|
+
* `'major'` or `'minor'`.
|
|
79
|
+
* @example
|
|
80
|
+
* ```ts
|
|
81
|
+
* import { keyFromFifths, formatNote } from '@libraz/libcantus';
|
|
82
|
+
* formatNote(keyFromFifths(-2).tonic); // 'Bb'
|
|
83
|
+
* formatNote(keyFromFifths(-2, 'minor').tonic); // 'G'
|
|
84
|
+
* ```
|
|
85
|
+
* @category Scales
|
|
86
|
+
*/
|
|
87
|
+
declare function keyFromFifths(fifths: number, mode?: KeyMode): ResolvedKey;
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Scale systems: which pitch organisations functional harmony was built for,
|
|
91
|
+
* and which ones it would only be imposed on.
|
|
92
|
+
*
|
|
93
|
+
* Roman numerals, tonic/subdominant/dominant function and cadence detection all
|
|
94
|
+
* presuppose Western common practice. A `KeyScale` is a root pitch class and a
|
|
95
|
+
* twelve-bit mask, which says nothing about the tradition the scale came from,
|
|
96
|
+
* so analysis code that wants to branch instead of assuming needs this
|
|
97
|
+
* classification to branch on.
|
|
98
|
+
*/
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The kind of pitch organisation a scale belongs to.
|
|
102
|
+
*
|
|
103
|
+
* - `'common-practice'`: the scale functional harmony is defined on — a tonic,
|
|
104
|
+
* a dominant carrying a leading tone, and a triad available on every degree.
|
|
105
|
+
* - `'modal'`: a seven-note rotation or alteration of that material. Degrees
|
|
106
|
+
* and Roman numerals still describe it, but a dominant-to-tonic cadence is
|
|
107
|
+
* not what holds the music together.
|
|
108
|
+
* - `'non-functional'`: the collection carries no chord function of its own. A
|
|
109
|
+
* gapped or symmetric set takes its harmony from whatever key it is used
|
|
110
|
+
* over, and a scale from a tradition organised melodically rather than by
|
|
111
|
+
* chords has no functional reading at all.
|
|
112
|
+
*
|
|
113
|
+
* @category Scales
|
|
114
|
+
*/
|
|
115
|
+
type ScaleSystem = 'common-practice' | 'modal' | 'non-functional';
|
|
116
|
+
/**
|
|
117
|
+
* The system each built-in scale belongs to.
|
|
118
|
+
*
|
|
119
|
+
* Every name in {@link NAMED_SCALES} and {@link WORLD_SCALES} appears here, so
|
|
120
|
+
* a scale added without a classification fails to compile rather than falling
|
|
121
|
+
* silently into a default. Aliases are classified through the name they resolve
|
|
122
|
+
* to; use {@link scaleSystemOf} to look one up.
|
|
123
|
+
*
|
|
124
|
+
* @category Scales
|
|
125
|
+
*/
|
|
126
|
+
declare const SCALE_SYSTEMS: Readonly<Record<ScaleName | WorldScaleName, ScaleSystem>>;
|
|
127
|
+
/**
|
|
128
|
+
* The system a scale belongs to.
|
|
129
|
+
*
|
|
130
|
+
* A name — canonical or an alias — is answered exactly: `'nahawand'` is a maqam
|
|
131
|
+
* even though its mask is the natural minor's. A `KeyScale` carries no
|
|
132
|
+
* tradition, so it is answered by its mask, under the Western reading of that
|
|
133
|
+
* mask; a mask that is no built-in scale answers undefined.
|
|
134
|
+
*
|
|
135
|
+
* @param scale The scale name, or a key/scale to read the mask of.
|
|
136
|
+
* @returns The system, or undefined for a mask that names no built-in scale.
|
|
137
|
+
* @throws If `scale` is a string naming no built-in scale. An unknown name is a
|
|
138
|
+
* typo, and answering it the way an unrecognised mask is answered would hide
|
|
139
|
+
* that.
|
|
140
|
+
* @example
|
|
141
|
+
* ```ts
|
|
142
|
+
* import { scaleSystemOf, majorKey } from '@libraz/libcantus';
|
|
143
|
+
* scaleSystemOf('harmonicMinor'); // 'common-practice'
|
|
144
|
+
* scaleSystemOf('dorian'); // 'modal'
|
|
145
|
+
* scaleSystemOf('hijaz'); // 'non-functional'
|
|
146
|
+
* scaleSystemOf(majorKey(0)); // 'common-practice'
|
|
147
|
+
* ```
|
|
148
|
+
* @category Scales
|
|
149
|
+
*/
|
|
150
|
+
declare function scaleSystemOf(scale: KeyScale | ScaleNameInput): ScaleSystem | undefined;
|
|
151
|
+
/**
|
|
152
|
+
* Whether functional (Roman-numeral) analysis applies to a scale.
|
|
153
|
+
*
|
|
154
|
+
* True for common-practice and modal scales, false for everything classed
|
|
155
|
+
* `'non-functional'` — analysis that would otherwise read a raga as a chord
|
|
156
|
+
* progression can ask here first.
|
|
157
|
+
*
|
|
158
|
+
* The two ways of naming a scale are answered differently, exactly as
|
|
159
|
+
* {@link scaleSystemOf} answers them. A name carries its tradition, so
|
|
160
|
+
* `'hijaz'` is false. A `KeyScale` carries only a mask, and a mask shared with
|
|
161
|
+
* a Western scale is read the Western way — maqam Hijaz and the phrygian
|
|
162
|
+
* dominant are the same seven pitch classes, so that mask is modal and answers
|
|
163
|
+
* true. A mask that names no built-in scale answers true as well, which keeps a
|
|
164
|
+
* caller's own mask being analysed the way it always has been. Pass the name
|
|
165
|
+
* whenever the tradition is known and the answer should follow it.
|
|
166
|
+
*
|
|
167
|
+
* @param scale The scale name, or a key/scale to read the mask of.
|
|
168
|
+
* @returns True when functional harmony describes the scale.
|
|
169
|
+
* @throws If `scale` is a string naming no built-in scale.
|
|
170
|
+
* @example
|
|
171
|
+
* ```ts
|
|
172
|
+
* import { supportsFunctionalHarmony, scaleByName } from '@libraz/libcantus';
|
|
173
|
+
* supportsFunctionalHarmony('harmonicMinor'); // true
|
|
174
|
+
* supportsFunctionalHarmony('bhairav'); // false
|
|
175
|
+
* supportsFunctionalHarmony('hijaz'); // false — named, so read as a maqam
|
|
176
|
+
* supportsFunctionalHarmony(scaleByName('hijaz', 0)); // true — its mask is the phrygian dominant
|
|
177
|
+
* supportsFunctionalHarmony(scaleByName('ryukyu', 0)); // false — a mask no Western scale shares
|
|
178
|
+
* ```
|
|
179
|
+
* @category Scales
|
|
180
|
+
*/
|
|
181
|
+
declare function supportsFunctionalHarmony(scale: KeyScale | ScaleNameInput): boolean;
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Lead-sheet chord symbol parsing and formatting.
|
|
185
|
+
*
|
|
186
|
+
* Bridges the informal `<root><quality>[/<bass>]` notation musicians write
|
|
187
|
+
* (`Cmaj7`, `F#m7b5`, `Bb7`, `C/G`) and the library's structured {@link Chord}
|
|
188
|
+
* type, so callers can accept/emit plain text at the edges of the API.
|
|
189
|
+
*
|
|
190
|
+
* The root and the slash bass are note names, so they are read and written in
|
|
191
|
+
* whichever notation system the caller names — a German chart's `H7`, `As7` and
|
|
192
|
+
* `Ges/B` included. Unlike a note name, a chord symbol is never attributed to a
|
|
193
|
+
* system on its own: German `B` is a B flat and English `B` a B natural, and a
|
|
194
|
+
* symbol carries no `dur`/`moll` word to break the tie, so the most common
|
|
195
|
+
* symbol in the vocabulary would otherwise change chord with the source it came
|
|
196
|
+
* from. With no system given a symbol is English.
|
|
197
|
+
*/
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Parse a lead-sheet chord symbol into a {@link Chord}.
|
|
201
|
+
*
|
|
202
|
+
* Accepts `<root><quality>[/<bass>]`, e.g. `Cmaj7`, `F#m7b5`, `Bb7`, `C/G`,
|
|
203
|
+
* `C6/9`, `C6/9/E`. Root and bass letters are case-insensitive, matching
|
|
204
|
+
* {@link parseNote}. A `/` is ambiguous between a slash bass and the `6/9`
|
|
205
|
+
* quality; the text splits at the last `/` whose right-hand side is a valid
|
|
206
|
+
* bare note preceded by a recognized quality, so `6/9` (with or without a
|
|
207
|
+
* further slash bass) parses as a quality.
|
|
208
|
+
*
|
|
209
|
+
* The root and bass are read in `system`, so a German chart's `H7`, `As7` and
|
|
210
|
+
* `Ges/B` are read by asking for `'german'`. The system is never inferred: with
|
|
211
|
+
* none given the symbol is English, where `B` is the B natural and `H` no note
|
|
212
|
+
* at all. Case carries nothing in a chord symbol — unlike a German key name,
|
|
213
|
+
* where the case of the tonic is the mode — so the quality suffix alone says
|
|
214
|
+
* major or minor. Where a German root's flat suffix could equally open the
|
|
215
|
+
* quality, the longest root that leaves a known quality behind wins: `Asus4` is
|
|
216
|
+
* an A suspended chord and `Assus4` the A flat one.
|
|
217
|
+
*
|
|
218
|
+
* The quality suffix is read structurally when no name covers it, so a chart's
|
|
219
|
+
* bracketed tensions parse as readily as the names do: `Cmaj7(#11)`,
|
|
220
|
+
* `C7(b9,#11)`, `C7(13)`, `Csus4(add9)`, `C-Δ9`, `C6/9(#11)`. A `/` between two
|
|
221
|
+
* figures separates them as it does inside brackets, which is what the sixth
|
|
222
|
+
* and ninth of a `6/9` are. Such a chord carries the tones it names and reports
|
|
223
|
+
* the nearest quality name (see {@link chordSpecQuality}); read
|
|
224
|
+
* {@link chordSpecOf} for its structure.
|
|
225
|
+
*
|
|
226
|
+
* The parsed chord carries the root/bass spellings as enharmonic hints
|
|
227
|
+
* (`rootSpelling`/`bassSpelling`) so {@link formatChordSymbol} can reproduce
|
|
228
|
+
* flat spellings such as `Bbmaj7` instead of respelling them with sharps.
|
|
229
|
+
*
|
|
230
|
+
* @param text The chord symbol text.
|
|
231
|
+
* @param opts `system` reads the root and bass in that notation system instead
|
|
232
|
+
* of English.
|
|
233
|
+
* @returns The parsed chord.
|
|
234
|
+
* @throws If the root or quality is not recognized in that system. Use
|
|
235
|
+
* {@link tryParseChordSymbol} where failure is ordinary, such as a chord
|
|
236
|
+
* field read on every keystroke.
|
|
237
|
+
* @example
|
|
238
|
+
* ```ts
|
|
239
|
+
* import { parseChordSymbol, formatChordSymbol } from '@libraz/libcantus';
|
|
240
|
+
* const c = parseChordSymbol('Bbmaj7');
|
|
241
|
+
* formatChordSymbol(c); // 'Bbmaj7' — flat spelling is preserved on round-trip
|
|
242
|
+
* parseChordSymbol('H7', { system: 'german' }).rootPc; // 11 — the B natural
|
|
243
|
+
* parseChordSymbol('B', { system: 'german' }).rootPc; // 10 — the German B flat
|
|
244
|
+
* ```
|
|
245
|
+
* @category Chords
|
|
246
|
+
*/
|
|
247
|
+
declare function parseChordSymbol(text: string, opts?: NoteNameOptions): Chord;
|
|
248
|
+
/**
|
|
249
|
+
* Parse a lead-sheet chord symbol, reporting failure instead of throwing it.
|
|
250
|
+
*
|
|
251
|
+
* The same reading as {@link parseChordSymbol} — that function is this one with
|
|
252
|
+
* its error thrown — for the callers where a symbol that does not parse yet is
|
|
253
|
+
* the normal state of the input rather than a fault: a chord field says what is
|
|
254
|
+
* wrong with what has been typed so far, and does not need a `try` around every
|
|
255
|
+
* keystroke to do it.
|
|
256
|
+
*
|
|
257
|
+
* @param text The chord symbol text.
|
|
258
|
+
* @param opts `system` reads the root and bass in that notation system instead
|
|
259
|
+
* of English.
|
|
260
|
+
* @returns The chord, or the error explaining why the text is not one.
|
|
261
|
+
* @example
|
|
262
|
+
* ```ts
|
|
263
|
+
* import { tryParseChordSymbol } from '@libraz/libcantus';
|
|
264
|
+
* const result = tryParseChordSymbol('Cmaj7(#11)');
|
|
265
|
+
* result.ok ? result.value.intervals : result.error.message;
|
|
266
|
+
* ```
|
|
267
|
+
* @category Chords
|
|
268
|
+
*/
|
|
269
|
+
declare function tryParseChordSymbol(text: string, opts?: NoteNameOptions): ParseResult<Chord>;
|
|
270
|
+
/**
|
|
271
|
+
* How a chord symbol is written: in which notation system, and on which side of
|
|
272
|
+
* the enharmonic fence.
|
|
273
|
+
*
|
|
274
|
+
* @category Chords
|
|
275
|
+
*/
|
|
276
|
+
type ChordSymbolOptions = NoteNameOptions & {
|
|
277
|
+
/**
|
|
278
|
+
* Which side of the staff the whole symbol is written on: `true` writes it in
|
|
279
|
+
* flats, `false` in sharps. The root, the slash bass and the chord's tones are
|
|
280
|
+
* spelled together, so a symbol never pairs a flat root with a sharp bass, and
|
|
281
|
+
* a spelling hint already on the requested side is kept rather than renamed.
|
|
282
|
+
* Where that side cannot spell the chord at all, the spelling a chart writes
|
|
283
|
+
* wins over an unwritable one.
|
|
284
|
+
*/
|
|
285
|
+
flats?: boolean;
|
|
286
|
+
};
|
|
287
|
+
/**
|
|
288
|
+
* Format a {@link Chord} as a lead-sheet chord symbol.
|
|
289
|
+
*
|
|
290
|
+
* The inverse of {@link parseChordSymbol} in every notation system: each
|
|
291
|
+
* quality maps to one canonical suffix spelling, the root and bass are written
|
|
292
|
+
* in `system`, and a slash bass is appended only when it differs from the root.
|
|
293
|
+
* Every symbol written here reads back through {@link parseChordSymbol} as the
|
|
294
|
+
* same root, sounding bass and tones apart from the degrees the chord omits —
|
|
295
|
+
* whatever combination of tensions it carries, and whether or not a quality
|
|
296
|
+
* name covers it. Those omissions are the one difference the round trip has: a
|
|
297
|
+
* chord that leaves a degree out is written without saying so, so reading the
|
|
298
|
+
* symbol back puts the degree in.
|
|
299
|
+
* When the chord carries `rootSpelling`/`bassSpelling` hints (as chords from
|
|
300
|
+
* {@link parseChordSymbol} do) and no explicit `flats` preference is given, the
|
|
301
|
+
* hints are reused so flat symbols round-trip unchanged.
|
|
302
|
+
*
|
|
303
|
+
* The suffix is written from the chord's own tones (see {@link chordSpecOf}),
|
|
304
|
+
* not from its quality name, so a chord carrying alterations no name covers is
|
|
305
|
+
* written out in full — `C7(b9,#11)` — rather than under the nearest name. A
|
|
306
|
+
* tone the chord leaves out is not written: the symbol names the harmony, so a
|
|
307
|
+
* fifth-less dominant is still `C7`.
|
|
308
|
+
*
|
|
309
|
+
* @param chord The chord to format, as a chord symbol, chord data, or a
|
|
310
|
+
* `Chord`.
|
|
311
|
+
* @param opts `system` writes the root and bass in that notation system instead
|
|
312
|
+
* of English; `flats` chooses the side of the staff the whole symbol is
|
|
313
|
+
* written on, as {@link ChordSymbolOptions} describes.
|
|
314
|
+
* @returns The chord symbol text.
|
|
315
|
+
* @example
|
|
316
|
+
* ```ts
|
|
317
|
+
* import { makeChord, formatChordSymbol, parseChordSymbol } from '@libraz/libcantus';
|
|
318
|
+
* formatChordSymbol(makeChord(0, 'min7')); // 'Cm7'
|
|
319
|
+
* formatChordSymbol(parseChordSymbol('Bb7'), { system: 'german' }); // 'B7'
|
|
320
|
+
* formatChordSymbol(parseChordSymbol('B7'), { system: 'german' }); // 'H7'
|
|
321
|
+
* ```
|
|
322
|
+
* @category Chords
|
|
323
|
+
*/
|
|
324
|
+
declare function formatChordSymbol(chord: ChordLike, opts?: ChordSymbolOptions): string;
|
|
325
|
+
/**
|
|
326
|
+
* Transpose a chord symbol by a number of semitones.
|
|
327
|
+
*
|
|
328
|
+
* The symbol is read in the same system it is written back in, so a German
|
|
329
|
+
* chart stays German across the transposition.
|
|
330
|
+
*
|
|
331
|
+
* The root and the bass are respelled where moving them by letter would leave
|
|
332
|
+
* a name no chart writes, so raising a flat chart a semitone gives `Bmaj7`
|
|
333
|
+
* rather than `Cbmaj7`. Pass `flats` to write the whole symbol on one side of
|
|
334
|
+
* the staff, root and bass together.
|
|
335
|
+
*
|
|
336
|
+
* @param text The chord symbol text.
|
|
337
|
+
* @param semitones Signed semitone offset to apply to the root and bass.
|
|
338
|
+
* @param opts Options for reading and writing the symbol; see
|
|
339
|
+
* {@link ChordSymbolOptions}.
|
|
340
|
+
* @returns The transposed chord symbol text.
|
|
341
|
+
* @throws If `text` does not parse as a chord symbol.
|
|
342
|
+
* @example
|
|
343
|
+
* ```ts
|
|
344
|
+
* import { transposeChordSymbol } from '@libraz/libcantus';
|
|
345
|
+
* transposeChordSymbol('C/G', 2); // 'D/A'
|
|
346
|
+
* transposeChordSymbol('H7', 1, { system: 'german' }); // 'C7'
|
|
347
|
+
* ```
|
|
348
|
+
* @category Chords
|
|
349
|
+
*/
|
|
350
|
+
declare function transposeChordSymbol(text: string, semitones: number, opts?: ChordSymbolOptions): string;
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Test whether every chord pitch class is contained in a scale.
|
|
354
|
+
*
|
|
355
|
+
* @param chordPcs The chord's pitch classes (0..11).
|
|
356
|
+
* @param scaleMask The scale's 12-bit mode mask.
|
|
357
|
+
* @param scaleRootPc The pitch class the mask is rooted on.
|
|
358
|
+
* @returns True if the scale is a superset of the chord.
|
|
359
|
+
*
|
|
360
|
+
* @category Scales
|
|
361
|
+
*/
|
|
362
|
+
declare function scaleMatchesChord(chordPcs: number[], scaleMask: number, scaleRootPc: number): boolean;
|
|
363
|
+
/**
|
|
364
|
+
* A named scale rooted on a pitch class that fits over a chord.
|
|
365
|
+
*
|
|
366
|
+
* @category Scales
|
|
367
|
+
*/
|
|
368
|
+
type ChordScaleMatch = {
|
|
369
|
+
name: string;
|
|
370
|
+
rootPc: number;
|
|
371
|
+
};
|
|
372
|
+
/**
|
|
373
|
+
* List the scales that fit over a chord, best fit first.
|
|
374
|
+
*
|
|
375
|
+
* Only the chord root is considered as the scale root, matching the
|
|
376
|
+
* conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
|
|
377
|
+
* whose pitch-class set is a superset of the chord's is returned once per
|
|
378
|
+
* distinct pitch-class set (aliased masks such as major/ionian report only the
|
|
379
|
+
* modal name). The chromatic scale is only returned as a fallback when no other
|
|
380
|
+
* scale contains the chord.
|
|
381
|
+
*
|
|
382
|
+
* The ranking applies these keys in order:
|
|
383
|
+
*
|
|
384
|
+
* 1. The idiomatic scales for the chord quality, in the order they are named
|
|
385
|
+
* there, ahead of every scale that is not one of them.
|
|
386
|
+
* 2. For bare triads and smaller chords, heptatonic scales ahead of pentatonics
|
|
387
|
+
* and other sizes: a pentatonic adds no modal color over a triad, so the
|
|
388
|
+
* seven-note modes are the more useful answer.
|
|
389
|
+
* 3. Fewest extra scale tones beyond the chord.
|
|
390
|
+
* 4. Conventional modal preference.
|
|
391
|
+
* 5. Fewest avoid notes, which separates the symmetric and melodic-minor
|
|
392
|
+
* scales the modal preference does not name.
|
|
393
|
+
* 6. Alphabetical order, so the list is stable.
|
|
394
|
+
*
|
|
395
|
+
* The idiomatic key comes first, so the head of the list is the scale a player
|
|
396
|
+
* would name rather than the tightest fit: over `Cm7b5` the locrian mode leads
|
|
397
|
+
* even though the blues scale adds fewer tones, because locrian is what a
|
|
398
|
+
* half-diminished chord is read as. Read further down the list, or pick by name,
|
|
399
|
+
* when the closest fit is what is wanted; {@link scalesForChanges} makes the
|
|
400
|
+
* choice for a whole progression.
|
|
401
|
+
*
|
|
402
|
+
* @param chord The chord to fit scales over, as a chord symbol, chord data, or
|
|
403
|
+
* a `Chord`.
|
|
404
|
+
* @returns The matching scales rooted on the chord root, best fit first.
|
|
405
|
+
*
|
|
406
|
+
* @example
|
|
407
|
+
* ```ts
|
|
408
|
+
* import { makeChord, chordScales } from '@libraz/libcantus';
|
|
409
|
+
* const scales = chordScales(makeChord(0, 'maj7'));
|
|
410
|
+
* // scales for Cmaj7, best fit first; each is { name, rootPc: 0 }
|
|
411
|
+
* ```
|
|
412
|
+
*
|
|
413
|
+
* @category Scales
|
|
414
|
+
*/
|
|
415
|
+
declare function chordScales(chord: ChordLike): ChordScaleMatch[];
|
|
416
|
+
/**
|
|
417
|
+
* Which use an avoid note is judged for: sounding it, or passing through it.
|
|
418
|
+
*
|
|
419
|
+
* `'harmonic'` is the Berklee-style rule — a tone that must not be
|
|
420
|
+
* sounded against the chord. `'melodic'` keeps only what a line cannot pass
|
|
421
|
+
* through either, which is the semitone above the root; every other clash
|
|
422
|
+
* resolves as the line moves on. Over a chord that sounds a dominant seventh
|
|
423
|
+
* the semitone above the root is the flat ninth, a tension under either use
|
|
424
|
+
* whichever scale supplies it; the flat thirteenth stays a harmonic avoid note.
|
|
425
|
+
*
|
|
426
|
+
* @category Scales
|
|
427
|
+
*/
|
|
428
|
+
type AvoidNoteUse = 'harmonic' | 'melodic';
|
|
429
|
+
/**
|
|
430
|
+
* Options for {@link avoidNotes}.
|
|
431
|
+
*
|
|
432
|
+
* @category Scales
|
|
433
|
+
*/
|
|
434
|
+
type AvoidNotesOptions = {
|
|
435
|
+
use?: AvoidNoteUse;
|
|
436
|
+
};
|
|
437
|
+
/**
|
|
438
|
+
* List a scale's avoid notes over a chord.
|
|
439
|
+
*
|
|
440
|
+
* An avoid note is a non-chord scale tone that lies a semitone directly above a
|
|
441
|
+
* chord tone, or the third a suspension displaced; sounding it against the
|
|
442
|
+
* chord clashes. The scale is rooted on the chord root. If the scale does not
|
|
443
|
+
* contain the chord, no avoid notes exist.
|
|
444
|
+
*
|
|
445
|
+
* The rule states which tones must not be *sounded* against the chord, which is
|
|
446
|
+
* not the same question as which tones a line may not touch. Pass
|
|
447
|
+
* `{ use: 'melodic' }` for the melodic reading: only the semitone above the
|
|
448
|
+
* root survives it, so the result is always a subset of the harmonic one.
|
|
449
|
+
*
|
|
450
|
+
* @param chord The chord providing the chord tones, as a chord symbol, chord
|
|
451
|
+
* data, or a `Chord`.
|
|
452
|
+
* @param scaleName A key of {@link NAMED_SCALES}, or an alias of one. A world
|
|
453
|
+
* scale is not one: chord-scale theory is a Western practice, so a raga named
|
|
454
|
+
* here is rejected rather than answered with a number.
|
|
455
|
+
* @param opts Set `use: 'melodic'` to judge a line rather than a voicing.
|
|
456
|
+
* @returns The avoid-note pitch classes, sorted ascending in [0, 11].
|
|
457
|
+
* @throws If `scaleName` is not a built-in scale. An empty result already
|
|
458
|
+
* means "this scale has no avoid notes over this chord"; answering a typo
|
|
459
|
+
* the same way would make the two indistinguishable.
|
|
460
|
+
*
|
|
461
|
+
* @example
|
|
462
|
+
* ```ts
|
|
463
|
+
* import { makeChord, avoidNotes } from '@libraz/libcantus';
|
|
464
|
+
* avoidNotes(makeChord(0, 'maj7'), 'ionian'); // [5] — F clashes with the third
|
|
465
|
+
* avoidNotes(makeChord(0, 'maj7'), 'ionian', { use: 'melodic' }); // [] — a line may pass through it
|
|
466
|
+
* ```
|
|
467
|
+
*
|
|
468
|
+
* @category Scales
|
|
469
|
+
*/
|
|
470
|
+
declare function avoidNotes(chord: ChordLike, scaleName: ScaleNameInput, opts?: AvoidNotesOptions): number[];
|
|
471
|
+
/**
|
|
472
|
+
* Options for {@link availableTensions}.
|
|
473
|
+
*
|
|
474
|
+
* @category Scales
|
|
475
|
+
*/
|
|
476
|
+
type AvailableTensionsOptions = {
|
|
477
|
+
/**
|
|
478
|
+
* The chord this one resolves to, as a chord symbol, chord data, or a
|
|
479
|
+
* `Chord`.
|
|
480
|
+
*/
|
|
481
|
+
resolvesTo?: ChordLike;
|
|
482
|
+
};
|
|
483
|
+
/**
|
|
484
|
+
* List a scale's available tensions over a chord.
|
|
485
|
+
*
|
|
486
|
+
* Available tensions are scale tones that are neither chord tones nor avoid
|
|
487
|
+
* notes, i.e. the usable color tones (typically the 9/11/13 region). The scale
|
|
488
|
+
* is rooted on the chord root. If the scale does not contain the chord, there
|
|
489
|
+
* are no available tensions.
|
|
490
|
+
*
|
|
491
|
+
* A tension's availability also depends on what the chord is doing. Pass
|
|
492
|
+
* `resolvesTo` to say which chord this one resolves to: a dominant seventh
|
|
493
|
+
* resolving down a fifth to a minor tonic takes its sharp ninth and flat
|
|
494
|
+
* thirteenth as well as the flat ninth every dominant takes. Only
|
|
495
|
+
* scale tones are ever added, so the result stays within the scale.
|
|
496
|
+
*
|
|
497
|
+
* @param chord The chord providing the chord tones, as a chord symbol, chord
|
|
498
|
+
* data, or a `Chord`.
|
|
499
|
+
* @param scaleName A key of {@link NAMED_SCALES}, or an alias of one; a world
|
|
500
|
+
* scale is outside chord-scale theory, as in {@link avoidNotes}.
|
|
501
|
+
* @param opts Set `resolvesTo` to the chord this one resolves to.
|
|
502
|
+
* @returns The available-tension pitch classes, sorted ascending in [0, 11].
|
|
503
|
+
* @throws If `scaleName` is not a built-in scale, as {@link avoidNotes} does.
|
|
504
|
+
*
|
|
505
|
+
* @example
|
|
506
|
+
* ```ts
|
|
507
|
+
* import { makeChord, availableTensions } from '@libraz/libcantus';
|
|
508
|
+
* availableTensions(makeChord(0, 'maj7'), 'ionian'); // [2, 9] — color tones over Cmaj7
|
|
509
|
+
* availableTensions(makeChord(7, 'dom7'), 'phrygianDominant', { resolvesTo: makeChord(0, 'min') });
|
|
510
|
+
* // [3, 8] — the b9, and the b13 the resolution to C minor makes available
|
|
511
|
+
* ```
|
|
512
|
+
*
|
|
513
|
+
* @category Scales
|
|
514
|
+
*/
|
|
515
|
+
declare function availableTensions(chord: ChordLike, scaleName: ScaleNameInput, opts?: AvailableTensionsOptions): number[];
|
|
516
|
+
/**
|
|
517
|
+
* A scale fit over a chord, with its non-chord tones sorted by what may be done
|
|
518
|
+
* with them.
|
|
519
|
+
*
|
|
520
|
+
* `avoid`, `passing` and `tensions` partition the scale tones the chord does
|
|
521
|
+
* not state: `avoid` may not be played at all, `passing` may be passed through
|
|
522
|
+
* melodically but not sounded against the chord, and `tensions` may be added
|
|
523
|
+
* freely as color. `avoid` is {@link avoidNotes} under `use: 'melodic'`, and
|
|
524
|
+
* `avoid` together with `passing` is the harmonic reading.
|
|
525
|
+
*
|
|
526
|
+
* @category Scales
|
|
527
|
+
*/
|
|
528
|
+
type ChordScaleReportEntry = {
|
|
529
|
+
name: string;
|
|
530
|
+
rootPc: number;
|
|
531
|
+
avoid: number[];
|
|
532
|
+
passing: number[];
|
|
533
|
+
tensions: number[];
|
|
534
|
+
};
|
|
535
|
+
/**
|
|
536
|
+
* Report the best-fitting scales for a chord with their avoid notes and tensions.
|
|
537
|
+
*
|
|
538
|
+
* Combines {@link chordScales}, {@link avoidNotes}, and {@link availableTensions}
|
|
539
|
+
* into a single ergonomic result, ordered best fit first. The report is read as
|
|
540
|
+
* playing advice, so the tones a line may pass through are reported apart from
|
|
541
|
+
* the ones it may not touch; see {@link ChordScaleReportEntry}.
|
|
542
|
+
*
|
|
543
|
+
* @param chord The chord to analyze, as a chord symbol, chord data, or a
|
|
544
|
+
* `Chord`.
|
|
545
|
+
* @param limit Optional maximum number of scales to report; all by default.
|
|
546
|
+
* @returns One entry per reported scale, best fit first.
|
|
547
|
+
*
|
|
548
|
+
* @category Scales
|
|
549
|
+
*/
|
|
550
|
+
declare function chordScaleReport(chord: ChordLike, limit?: number): ChordScaleReportEntry[];
|
|
551
|
+
/**
|
|
552
|
+
* A chord paired with the scale chosen for it by {@link scalesForChanges}.
|
|
553
|
+
*
|
|
554
|
+
* @category Scales
|
|
555
|
+
*/
|
|
556
|
+
type ScaleChoice = {
|
|
557
|
+
chord: Chord;
|
|
558
|
+
scale: ChordScaleMatch;
|
|
559
|
+
};
|
|
560
|
+
/**
|
|
561
|
+
* Choose one scale per chord across a progression, favoring continuity.
|
|
562
|
+
*
|
|
563
|
+
* Each chord's {@link chordScales} candidates form a stage in a Viterbi-style
|
|
564
|
+
* dynamic program. The transition cost between adjacent choices is the number
|
|
565
|
+
* of pitch classes that differ between their pitch-class sets (the symmetric
|
|
566
|
+
* difference), plus a small penalty for straying from a chord's best-fit scale
|
|
567
|
+
* so that ties break toward the tighter fit. The minimum-total-cost path is
|
|
568
|
+
* returned, one {@link ScaleChoice} per input chord in the original order.
|
|
569
|
+
*
|
|
570
|
+
* Each choice pairs its scale with the chord exactly as it was handed in, so
|
|
571
|
+
* this takes plain chord data rather than the wider forms the entry points
|
|
572
|
+
* above accept.
|
|
573
|
+
*
|
|
574
|
+
* @param chords The chord sequence to choose scales for.
|
|
575
|
+
* @returns One scale choice per chord, in input order.
|
|
576
|
+
*
|
|
577
|
+
* @category Scales
|
|
578
|
+
*/
|
|
579
|
+
declare function scalesForChanges(chords: readonly Chord[]): ScaleChoice[];
|
|
580
|
+
|
|
581
|
+
/**
|
|
582
|
+
* Voice independence as a measurement rather than a verdict.
|
|
583
|
+
*
|
|
584
|
+
* The species rules answer "is this allowed", which is the wrong question of a
|
|
585
|
+
* pop arrangement: a harmony line in parallel thirds, a power-chord riff and a
|
|
586
|
+
* pedal point all break them and all are the intended sound. This module
|
|
587
|
+
* reports how independent two lines actually are and leaves the judgement to
|
|
588
|
+
* the caller.
|
|
589
|
+
*/
|
|
590
|
+
|
|
591
|
+
/**
|
|
592
|
+
* How two lines move against each other, and how far apart they sit.
|
|
593
|
+
*
|
|
594
|
+
* @category Voicing & Counterpoint
|
|
595
|
+
*/
|
|
596
|
+
type VoiceIndependenceReport = {
|
|
597
|
+
/**
|
|
598
|
+
* Share of the moves that fall into each motion type, summing to 1. A slot
|
|
599
|
+
* pair in which neither voice moves is not a move and is left out entirely,
|
|
600
|
+
* so an accompaniment that mostly sits still can still report mostly contrary
|
|
601
|
+
* motion. All four are 0 when nothing moves.
|
|
602
|
+
*/
|
|
603
|
+
motion: {
|
|
604
|
+
/** The voices move in opposite directions. */
|
|
605
|
+
contrary: number;
|
|
606
|
+
/** One voice holds while the other moves. */
|
|
607
|
+
oblique: number;
|
|
608
|
+
/** Both rise or both fall, and the interval between them changes. */
|
|
609
|
+
similar: number;
|
|
610
|
+
/** Both rise or both fall, keeping the same interval. */
|
|
611
|
+
parallel: number;
|
|
612
|
+
};
|
|
613
|
+
/**
|
|
614
|
+
* Share of the slots where the lead holds or rests on which the counter
|
|
615
|
+
* attacks: 1 when the counter fills every gap the lead leaves, 0 when it moves
|
|
616
|
+
* only where the lead does. It is 0 when the lead never holds or rests, since
|
|
617
|
+
* there was nothing to complement.
|
|
618
|
+
*/
|
|
619
|
+
rhythmicComplementarity: number;
|
|
620
|
+
/** Distance between the two lines, in semitones, over the slots where both sound. */
|
|
621
|
+
separation: {
|
|
622
|
+
/** Mean distance; 0 when the two lines never sound together. */
|
|
623
|
+
mean: number;
|
|
624
|
+
/** Closest approach; 0 when the two lines never sound together. */
|
|
625
|
+
min: number;
|
|
626
|
+
};
|
|
627
|
+
/**
|
|
628
|
+
* Slots at which the two lines sit in the opposite order to the one they keep
|
|
629
|
+
* overall. A unison is not a crossing.
|
|
630
|
+
*/
|
|
631
|
+
crossings: number;
|
|
632
|
+
/** Longest run of consecutive slots sounding a perfect consonance. */
|
|
633
|
+
longestPerfectRun: number;
|
|
634
|
+
/** Slots at which both lines sound, the denominator of `separation`. */
|
|
635
|
+
sounding: number;
|
|
636
|
+
};
|
|
637
|
+
/**
|
|
638
|
+
* Options controlling {@link voiceIndependence}.
|
|
639
|
+
*
|
|
640
|
+
* @category Voicing & Counterpoint
|
|
641
|
+
*/
|
|
642
|
+
type VoiceIndependenceOptions = {
|
|
643
|
+
/**
|
|
644
|
+
* Which slots are fresh attacks in the lead. Without it a slot counts as an
|
|
645
|
+
* attack when its note differs from the previous slot's, which reads a
|
|
646
|
+
* deliberately repeated note as a sustain.
|
|
647
|
+
*/
|
|
648
|
+
leadAttacks?: readonly boolean[];
|
|
649
|
+
/** Which slots are fresh attacks in the counter; read as `leadAttacks` is. */
|
|
650
|
+
counterAttacks?: readonly boolean[];
|
|
651
|
+
/**
|
|
652
|
+
* Count the perfect fourth among the perfect consonances when measuring
|
|
653
|
+
* `longestPerfectRun`. Useful for quartal writing, where the fourth is the
|
|
654
|
+
* interval being sustained.
|
|
655
|
+
*
|
|
656
|
+
* @defaultValue false
|
|
657
|
+
*/
|
|
658
|
+
countFourths?: boolean;
|
|
659
|
+
};
|
|
660
|
+
/**
|
|
661
|
+
* Measure how independent a counter line is from the lead it accompanies.
|
|
662
|
+
*
|
|
663
|
+
* Both lines are index-aligned samples: one slot per beat (or whatever grid the
|
|
664
|
+
* caller works on), `null` for a rest, and a repeated note for a sustain. That
|
|
665
|
+
* is what makes the rhythmic reading possible without a duration model, and
|
|
666
|
+
* what makes a re-attacked repeated note look like a sustain unless
|
|
667
|
+
* `leadAttacks` / `counterAttacks` say otherwise. Notes must carry octaves,
|
|
668
|
+
* since separation and motion are measured between sounding pitches.
|
|
669
|
+
*
|
|
670
|
+
* Nothing here is a verdict. Parallel thirds report as parallel motion with a
|
|
671
|
+
* small separation, a pedal point as oblique motion, a power-chord line as a
|
|
672
|
+
* long perfect run — all facts about the texture, not faults in it.
|
|
673
|
+
*
|
|
674
|
+
* @param lead The leading line, one entry per slot.
|
|
675
|
+
* @param counter The accompanying line, aligned slot for slot with `lead`.
|
|
676
|
+
* @param opts Attack flags and the treatment of the fourth.
|
|
677
|
+
* @returns The motion breakdown, rhythmic complementarity, separation,
|
|
678
|
+
* crossings, and the longest perfect-consonance run.
|
|
679
|
+
* @throws If the two lines differ in length, if an attack array is supplied at
|
|
680
|
+
* another length than the lines, or if a note carries no octave.
|
|
681
|
+
* @example
|
|
682
|
+
* ```ts
|
|
683
|
+
* import { parseNote, voiceIndependence } from '@libraz/libcantus';
|
|
684
|
+
* const lead = ['C5', 'D5', 'E5'].map((n) => parseNote(n));
|
|
685
|
+
* const counter = ['E4', 'F4', 'G4'].map((n) => parseNote(n));
|
|
686
|
+
* voiceIndependence(lead, counter).motion.parallel; // 1 — a harmony line in sixths
|
|
687
|
+
* ```
|
|
688
|
+
* @category Voicing & Counterpoint
|
|
689
|
+
*/
|
|
690
|
+
declare function voiceIndependence(lead: readonly (Note | null)[], counter: readonly (Note | null)[], opts?: VoiceIndependenceOptions): VoiceIndependenceReport;
|
|
691
|
+
|
|
692
|
+
/**
|
|
693
|
+
* An inclusive MIDI pitch range for a single voice.
|
|
694
|
+
*
|
|
695
|
+
* @category Voicing & Counterpoint
|
|
696
|
+
*/
|
|
697
|
+
type VoiceRange = {
|
|
698
|
+
readonly min: number;
|
|
699
|
+
readonly max: number;
|
|
700
|
+
};
|
|
701
|
+
/**
|
|
702
|
+
* Default four-voice SATB ranges, ascending (index 0 = lowest):
|
|
703
|
+
* bass E2–C4 (40–60), tenor C3–G4 (48–67), alto G3–D5 (55–74),
|
|
704
|
+
* soprano C4–G5 (60–79).
|
|
705
|
+
*
|
|
706
|
+
* @category Voicing & Counterpoint
|
|
707
|
+
*/
|
|
708
|
+
declare const SATB_RANGES: readonly Readonly<VoiceRange>[];
|
|
709
|
+
/**
|
|
710
|
+
* Options controlling {@link voiceChord} and {@link voiceProgression}.
|
|
711
|
+
*
|
|
712
|
+
* @category Voicing & Counterpoint
|
|
713
|
+
*/
|
|
714
|
+
type VoicingOptions = {
|
|
715
|
+
/**
|
|
716
|
+
* Number of voices to realize. Ignored when `ranges` is given.
|
|
717
|
+
*
|
|
718
|
+
* @defaultValue 4
|
|
719
|
+
*/
|
|
720
|
+
voices?: number;
|
|
721
|
+
/** Explicit per-voice ranges, ascending (index 0 = lowest). Takes precedence over `voices`. */
|
|
722
|
+
ranges?: VoiceRange[];
|
|
723
|
+
/**
|
|
724
|
+
* Maximum spacing in semitones between adjacent upper voices.
|
|
725
|
+
*
|
|
726
|
+
* @defaultValue 12
|
|
727
|
+
*/
|
|
728
|
+
maxSpacing?: number;
|
|
729
|
+
/**
|
|
730
|
+
* Maximum candidate voicings evaluated for one chord.
|
|
731
|
+
*
|
|
732
|
+
* Raise this for large voicings when exact optimum matters more than bounded
|
|
733
|
+
* search time.
|
|
734
|
+
*
|
|
735
|
+
* @defaultValue 4000
|
|
736
|
+
*/
|
|
737
|
+
maxCandidates?: number;
|
|
738
|
+
/**
|
|
739
|
+
* Maximum number of chords {@link voiceProgression} will voice. The search
|
|
740
|
+
* per chord is bounded internally, so the cost of a progression is linear in
|
|
741
|
+
* its length; this is the guard against an unbounded caller, not a limit on
|
|
742
|
+
* the search.
|
|
743
|
+
*
|
|
744
|
+
* @defaultValue 1000000
|
|
745
|
+
*/
|
|
746
|
+
budget?: number;
|
|
747
|
+
/**
|
|
748
|
+
* The prevailing key, as a key name, a key/scale, or a `Key`. Supplying it
|
|
749
|
+
* enables the rules that only make sense relative to a tonic: the leading
|
|
750
|
+
* tone is not doubled, and — where the chord being left is known as well —
|
|
751
|
+
* it is not left unresolved. Without it, voicings are chosen from chord
|
|
752
|
+
* structure and voice-leading distance alone.
|
|
753
|
+
*/
|
|
754
|
+
key?: KeyLike;
|
|
755
|
+
/**
|
|
756
|
+
* The chord the current voicing was written on, as a chord symbol, chord
|
|
757
|
+
* data, or a `Chord`.
|
|
758
|
+
*
|
|
759
|
+
* It enables every rule that is read from the chord being left: the
|
|
760
|
+
* resolution of a chordal seventh, the resolution of a leading tone, and the
|
|
761
|
+
* cross relation between the two chords. All three are scored exactly as
|
|
762
|
+
* {@link voiceProgression} scores them, and none of them is scored without
|
|
763
|
+
* it — a leading tone cannot be told from the third of a chord that merely
|
|
764
|
+
* contains it until the chord it belongs to is known. Supply it whenever the
|
|
765
|
+
* caller has the chord, not only where that chord carried a seventh.
|
|
766
|
+
*/
|
|
767
|
+
previousChord?: ChordLike;
|
|
768
|
+
};
|
|
769
|
+
/**
|
|
770
|
+
* Realize a single chord as one MIDI pitch per voice, ascending (index 0 =
|
|
771
|
+
* lowest). The bass voice takes the chord's `bassPc` when set, otherwise the
|
|
772
|
+
* root; upper voices take chord pitch classes, doubling the root or fifth as
|
|
773
|
+
* needed to fill all voices. The result stays inside each voice's range, keeps
|
|
774
|
+
* adjacent upper voices within `maxSpacing`, avoids voice crossing, and is
|
|
775
|
+
* deterministic: a compact close-position voicing centered in the ranges.
|
|
776
|
+
*
|
|
777
|
+
* @param chord The chord to voice.
|
|
778
|
+
* @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
|
|
779
|
+
* @returns MIDI pitches, ascending, one per voice.
|
|
780
|
+
* @throws If no voicing fits the given ranges.
|
|
781
|
+
* @example
|
|
782
|
+
* ```ts
|
|
783
|
+
* import { parseChordSymbol, voiceChord } from '@libraz/libcantus';
|
|
784
|
+
* const chord = parseChordSymbol('Cmaj7');
|
|
785
|
+
* voiceChord(chord); // four ascending MIDI pitches within the SATB ranges
|
|
786
|
+
* ```
|
|
787
|
+
* @category Voicing & Counterpoint
|
|
788
|
+
*/
|
|
789
|
+
declare function voiceChord(chord: ChordLike, opts?: VoicingOptions): number[];
|
|
790
|
+
/**
|
|
791
|
+
* Voice a chord progression with smooth voice leading. Each chord picks, from a
|
|
792
|
+
* bounded deterministic candidate set, the voicing minimizing the voice-leading
|
|
793
|
+
* cost from the previous voicing plus a large penalty per counterpoint
|
|
794
|
+
* violation (parallel perfects/octaves, voice crossing, voice overlap, and
|
|
795
|
+
* over-wide upper-voice spacing).
|
|
796
|
+
*
|
|
797
|
+
* The choice also weighs the chord that follows. A voicing costs whatever the
|
|
798
|
+
* move onto the next chord will cost in broken rules, so a placement that is
|
|
799
|
+
* marginally smoother now but strands a voice on a leap it cannot write cleanly
|
|
800
|
+
* loses to the one that leaves the line somewhere the next chord can be reached
|
|
801
|
+
* from. The lookahead is one chord deep and reads only the violation weight of
|
|
802
|
+
* the connection, so a chord is otherwise voiced exactly as it would be on its
|
|
803
|
+
* own merits.
|
|
804
|
+
*
|
|
805
|
+
* Tendency tones are resolved rather than merely moved economically: the voice
|
|
806
|
+
* holding a chordal seventh falls by step unless the next chord keeps that tone,
|
|
807
|
+
* and — when `opts.key` is given — the leading tone rises to the tonic and is
|
|
808
|
+
* never doubled, wherever it is functioning as a leading tone rather than
|
|
809
|
+
* sounding as an ordinary tone of some other chord. A key also names the letters
|
|
810
|
+
* each voice is written with, which is what lets the search refuse the augmented
|
|
811
|
+
* second between the lowered sixth and the raised seventh that a minor-key line
|
|
812
|
+
* otherwise falls into. Without a key neither rule can apply, since nothing
|
|
813
|
+
* identifies which pitch class is the leading tone or how a tone is spelled.
|
|
814
|
+
*
|
|
815
|
+
* @param chords The chords to voice in order.
|
|
816
|
+
* @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
|
|
817
|
+
* @returns One voicing per chord, each ascending with one MIDI pitch per voice.
|
|
818
|
+
* @throws {@link NoSolutionError} with the failing chord index when a chord
|
|
819
|
+
* admits no voicing within the given ranges, or if the progression is longer
|
|
820
|
+
* than `opts.budget` chords.
|
|
821
|
+
* @example
|
|
822
|
+
* ```ts
|
|
823
|
+
* import { parseChordSymbol, voiceProgression } from '@libraz/libcantus';
|
|
824
|
+
* const chords = ['C', 'Am', 'F', 'G'].map((s) => parseChordSymbol(s));
|
|
825
|
+
* voiceProgression(chords); // one four-voice voicing per chord, smoothly led
|
|
826
|
+
* ```
|
|
827
|
+
* @category Voicing & Counterpoint
|
|
828
|
+
*/
|
|
829
|
+
declare function voiceProgression(chords: readonly ChordLike[], opts?: VoicingOptions): number[][];
|
|
830
|
+
|
|
831
|
+
/**
|
|
832
|
+
* A tertian voicing style for {@link voiceChordStyled}.
|
|
833
|
+
*
|
|
834
|
+
* - `close`: the plain close-position tertian stack.
|
|
835
|
+
* - `drop2`: the second voice from the top dropped an octave (drop-2 voicing).
|
|
836
|
+
* It takes at least three voices, since the voice it names has to have
|
|
837
|
+
* another below it for the drop to open the stack at all.
|
|
838
|
+
* - `drop3`: the third voice from the top dropped an octave (drop-3 voicing).
|
|
839
|
+
* It takes at least four voices, for the same reason.
|
|
840
|
+
* - `shell`: root plus guide tones (third and seventh) for seventh chords, or
|
|
841
|
+
* root/third/fifth for triads; the fifth and tensions are omitted.
|
|
842
|
+
* - `rootless`: the root omitted, keeping third/fifth/seventh and tensions
|
|
843
|
+
* (a typical left-hand jazz voicing).
|
|
844
|
+
*
|
|
845
|
+
* A chord with too few voices for the drop it asks for is voiced in close
|
|
846
|
+
* position instead: a three-note `drop3` is the close stack, not a stack with
|
|
847
|
+
* its bottom voice pushed an octave down. A slash bass the chord does not
|
|
848
|
+
* contain sounds under the stack rather than in it, and is not one of the
|
|
849
|
+
* voices counted here.
|
|
850
|
+
*
|
|
851
|
+
* @category Voicing & Counterpoint
|
|
852
|
+
*/
|
|
853
|
+
type VoicingStyle = 'close' | 'drop2' | 'drop3' | 'shell' | 'rootless';
|
|
854
|
+
/**
|
|
855
|
+
* Options controlling {@link voiceChordStyled}.
|
|
856
|
+
*
|
|
857
|
+
* @category Voicing & Counterpoint
|
|
858
|
+
*/
|
|
859
|
+
type StyledVoicingOptions = {
|
|
860
|
+
/**
|
|
861
|
+
* Voicing style to build.
|
|
862
|
+
*
|
|
863
|
+
* @defaultValue 'close'
|
|
864
|
+
*/
|
|
865
|
+
style?: VoicingStyle;
|
|
866
|
+
/** Constrain the highest voice to this pitch class (0..11) when given. */
|
|
867
|
+
topNote?: number;
|
|
868
|
+
/**
|
|
869
|
+
* Base octave in scientific pitch notation: octave 4 starts the stack near
|
|
870
|
+
* middle C (MIDI 60), i.e. near `12 * (octave + 1)`.
|
|
871
|
+
*
|
|
872
|
+
* @defaultValue 4
|
|
873
|
+
*/
|
|
874
|
+
octave?: number;
|
|
875
|
+
/**
|
|
876
|
+
* Omit the root regardless of style (relevant for jazz voicings).
|
|
877
|
+
*
|
|
878
|
+
* @defaultValue false
|
|
879
|
+
*/
|
|
880
|
+
rootless?: boolean;
|
|
881
|
+
};
|
|
882
|
+
/**
|
|
883
|
+
* Realize a single chord as an explicit tertian voicing in a chosen style,
|
|
884
|
+
* independent of the SATB range search used by {@link voiceChord}.
|
|
885
|
+
*
|
|
886
|
+
* The chord tones are stacked in close position from the bass (`bassPc`, else
|
|
887
|
+
* `rootPc`) in the given scientific-pitch `octave` upward (octave 4 starts the
|
|
888
|
+
* bass near C4 = MIDI 60, matching {@link midiToNote} and the bass module).
|
|
889
|
+
* When `topNote` is given the stack is rotated so the highest voice's pitch
|
|
890
|
+
* class equals that note (or the nearest chord tone). The chosen
|
|
891
|
+
* {@link VoicingStyle} then transforms the stack, and the result is returned as
|
|
892
|
+
* ascending MIDI pitches (index 0 = lowest).
|
|
893
|
+
*
|
|
894
|
+
* A drop voicing lowers one voice by an octave. On a stack spanning no more than
|
|
895
|
+
* an octave above that voice it becomes the bass — which is what tells the
|
|
896
|
+
* drop-2 voicings of one chord apart; on a wider stack (an eleventh or
|
|
897
|
+
* thirteenth chord) it can land inside the stack. When the chord
|
|
898
|
+
* names a bass tone of its own, the close stack is therefore rotated so the
|
|
899
|
+
* style drops that tone, and the result is the drop voicing whose bass is the
|
|
900
|
+
* tone asked for; the named bass is not lowered under an already dropped voice
|
|
901
|
+
* afterwards, which would leave a hole wider than an octave in the middle. A
|
|
902
|
+
* bass the chord does not contain is no voice of the stack and cannot be the
|
|
903
|
+
* dropped one, so it keeps the bottom and the drop happens above it.
|
|
904
|
+
*
|
|
905
|
+
* Every returned pitch is a valid MIDI number: an octave whose stack would run
|
|
906
|
+
* off either end of the 0..127 range is rejected rather than voiced out of
|
|
907
|
+
* range, matching {@link nextVoicing}, which clamps its derived ranges.
|
|
908
|
+
*
|
|
909
|
+
* @param given The chord to voice, in whatever form it is held: a chord symbol,
|
|
910
|
+
* plain chord data, or a `Chord`.
|
|
911
|
+
* @param opts Styled voicing options; defaults to a close voicing at octave 4.
|
|
912
|
+
* @returns MIDI pitches, ascending, one per retained voice.
|
|
913
|
+
* @throws If the voicing would not fit inside MIDI 0..127 at the given octave,
|
|
914
|
+
* or `style` is not a {@link VoicingStyle}.
|
|
915
|
+
* @example
|
|
916
|
+
* ```ts
|
|
917
|
+
* import { voiceChordStyled } from '@libraz/libcantus';
|
|
918
|
+
* voiceChordStyled('Dm7', { style: 'drop2' }); // ascending MIDI pitches, drop-2 voicing
|
|
919
|
+
* ```
|
|
920
|
+
* @category Voicing & Counterpoint
|
|
921
|
+
*/
|
|
922
|
+
declare function voiceChordStyled(given: ChordLike, opts?: StyledVoicingOptions): number[];
|
|
923
|
+
|
|
924
|
+
/**
|
|
925
|
+
* Species counterpoint: mark a two-voice exercise against the sixteenth-century
|
|
926
|
+
* rules.
|
|
927
|
+
*
|
|
928
|
+
* This is the conservatory exercise, not a general style checker. It grades a
|
|
929
|
+
* counterpoint written above or below a given cantus firmus in one of the five
|
|
930
|
+
* species, and reports what it finds as the same {@link PartWritingViolation}
|
|
931
|
+
* the four-part checker uses.
|
|
932
|
+
*
|
|
933
|
+
* Both voices arrive as spelled notes, because half of what the rules forbid is
|
|
934
|
+
* invisible in a pitch: the augmented second of the harmonic minor is a minor
|
|
935
|
+
* third by ear, and the diminished fourth that may not stand as a consonance is
|
|
936
|
+
* a major third by ear.
|
|
937
|
+
*/
|
|
938
|
+
|
|
939
|
+
/**
|
|
940
|
+
* Which species an exercise is written in: note against note, two, three or
|
|
941
|
+
* four notes against one, suspensions, or the florid mixture of them all.
|
|
942
|
+
*
|
|
943
|
+
* @category Voicing & Counterpoint
|
|
944
|
+
*/
|
|
945
|
+
type Species = 1 | 2 | 3 | 4 | 5;
|
|
946
|
+
/**
|
|
947
|
+
* Options controlling {@link checkSpecies}.
|
|
948
|
+
*
|
|
949
|
+
* @category Voicing & Counterpoint
|
|
950
|
+
*/
|
|
951
|
+
type SpeciesOptions = {
|
|
952
|
+
/**
|
|
953
|
+
* Length of each counterpoint note, measured in cantus-firmus notes: 1 is a
|
|
954
|
+
* whole note filling a measure, 0.5 a half, 0.25 a quarter.
|
|
955
|
+
*
|
|
956
|
+
* The first four species have a fixed ratio, so the durations are implied by
|
|
957
|
+
* the note count and this is only needed to describe something unusual. The
|
|
958
|
+
* fifth species mixes note values by definition and cannot be read without it.
|
|
959
|
+
*/
|
|
960
|
+
durations?: readonly number[];
|
|
961
|
+
/**
|
|
962
|
+
* Which side of the cantus firmus the counterpoint is written on. Defaults to
|
|
963
|
+
* whichever side it actually lies on, by mean pitch.
|
|
964
|
+
*/
|
|
965
|
+
counterpointAbove?: boolean;
|
|
966
|
+
};
|
|
967
|
+
/**
|
|
968
|
+
* Check a species counterpoint exercise and report every rule it breaks.
|
|
969
|
+
*
|
|
970
|
+
* The cantus firmus is one note per measure. The counterpoint is aligned to it
|
|
971
|
+
* by position rather than by written rhythm: the first four species have a fixed
|
|
972
|
+
* number of notes per measure, so the note count alone says where each note
|
|
973
|
+
* falls, and a closing measure written as a single whole note is accepted as the
|
|
974
|
+
* convention it is. The fifth species mixes note values and therefore needs
|
|
975
|
+
* `opts.durations`, given in cantus-firmus notes.
|
|
976
|
+
*
|
|
977
|
+
* Judged are the vertical intervals under each species' dissonance licence
|
|
978
|
+
* (none in the first, a passing dissonance on the weak half in the second and
|
|
979
|
+
* third, a prepared suspension on the downbeat in the fourth, both in the
|
|
980
|
+
* fifth; the neighbour that turns back on its own note belongs to the
|
|
981
|
+
* quarter-note line of the third and fifth species, which also write the *nota
|
|
982
|
+
* cambiata* and the double neighbour, quitting a dissonance by leap). A note
|
|
983
|
+
* still sounding when the next cantus-firmus note is struck is judged against
|
|
984
|
+
* that note too, so a ligature carried across the bar line is read where it
|
|
985
|
+
* lands as well as where it began. Judged besides are parallel and hidden
|
|
986
|
+
* perfects and the *battuta* between the voices, augmented and otherwise
|
|
987
|
+
* forbidden leaps along the counterpoint, the shape of the counterpoint as a
|
|
988
|
+
* line, and the opening and closing formulas. Violations name the cantus firmus
|
|
989
|
+
* as voice 0 and the counterpoint as voice 1, and index into the counterpoint.
|
|
990
|
+
*
|
|
991
|
+
* @param cantusFirmus The given voice, one spelled note per measure.
|
|
992
|
+
* @param counterpoint The written voice, in spelled notes.
|
|
993
|
+
* @param species Which species the exercise is written in.
|
|
994
|
+
* @param modeLike The mode the exercise is in.
|
|
995
|
+
* @param opts Note lengths, and which side the counterpoint is written on.
|
|
996
|
+
* @returns Every violation found, in the order the exercise commits them; an
|
|
997
|
+
* empty array for a clean exercise.
|
|
998
|
+
* @throws If the species is not one of the five, either voice is empty, a note
|
|
999
|
+
* carries no octave, the durations are not an array of finite numbers, or the
|
|
1000
|
+
* fifth species is given without durations.
|
|
1001
|
+
* @example
|
|
1002
|
+
* ```ts
|
|
1003
|
+
* import { checkSpecies, majorKey, parseNote } from '@libraz/libcantus';
|
|
1004
|
+
* const cf = ['C4', 'D4', 'E4', 'D4', 'C4'].map((n) => parseNote(n));
|
|
1005
|
+
* const cp = ['C5', 'A4', 'G4', 'B4', 'C5'].map((n) => parseNote(n));
|
|
1006
|
+
* checkSpecies(cf, cp, 1, majorKey(0)); // [] — a clean first-species exercise
|
|
1007
|
+
* ```
|
|
1008
|
+
* @category Voicing & Counterpoint
|
|
1009
|
+
*/
|
|
1010
|
+
declare function checkSpecies(cantusFirmus: readonly Note[], counterpoint: readonly Note[], species: Species, modeLike: KeyLike, opts?: SpeciesOptions): PartWritingViolation[];
|
|
1011
|
+
|
|
1012
|
+
/**
|
|
1013
|
+
* Part writing: grade a finished exercise against the classical four-part rules.
|
|
1014
|
+
*
|
|
1015
|
+
* The counterpoint predicates each judge one pair of voices at one moment; this
|
|
1016
|
+
* module walks a whole progression and reports every violation it finds, so a
|
|
1017
|
+
* completed exercise can be marked in a single call.
|
|
1018
|
+
*
|
|
1019
|
+
* The input is spelled notes rather than MIDI pitches because two of the rules
|
|
1020
|
+
* cannot be decided without them: a cross relation is one letter carrying two
|
|
1021
|
+
* different accidentals, and an augmented second is a minor third under another
|
|
1022
|
+
* name. A caller holding only pitches spells them with {@link spellVoicing}.
|
|
1023
|
+
*/
|
|
1024
|
+
|
|
1025
|
+
/**
|
|
1026
|
+
* The rule a {@link PartWritingViolation} breaks.
|
|
1027
|
+
*
|
|
1028
|
+
* - `parallelFifth`, `parallelOctave`: consecutive perfect intervals of the same
|
|
1029
|
+
* kind between one pair of voices. A parallel unison is reported as a
|
|
1030
|
+
* `parallelOctave`, since it is the same perfect class.
|
|
1031
|
+
* - `hiddenPerfect`: the outer voices reach a perfect fifth or octave by similar
|
|
1032
|
+
* motion with a leap in the upper voice. The leap is what exposes it in a
|
|
1033
|
+
* four-part texture; in a two-voice species exercise nothing covers the
|
|
1034
|
+
* arrival, so similar motion into a perfect interval is reported however the
|
|
1035
|
+
* upper voice got there.
|
|
1036
|
+
* - `crossRelation`: one letter carries two different accidentals in two
|
|
1037
|
+
* different voices across a chord change, exposed — neither note led into by
|
|
1038
|
+
* step, at least one of them in an outer voice, and neither chord one of the
|
|
1039
|
+
* chromatic harmonies that are written with the contradiction.
|
|
1040
|
+
* - `voiceCrossing`, `overlap`, `spacing`, `range`: the texture rules.
|
|
1041
|
+
* - `unresolvedLeadingTone`, `unresolvedSeventh`: a tendency tone that does not
|
|
1042
|
+
* go where it must.
|
|
1043
|
+
* - `augmentedMelodicInterval`: a single voice moves by an augmented interval.
|
|
1044
|
+
*
|
|
1045
|
+
* The rest are raised by {@link checkSpecies} alone, since they describe faults
|
|
1046
|
+
* only a species exercise can commit:
|
|
1047
|
+
*
|
|
1048
|
+
* - `wrongRhythmicRatio`: the counterpoint's rhythm does not read against the
|
|
1049
|
+
* cantus firmus as its species requires — the wrong number of notes per
|
|
1050
|
+
* cantus-firmus note, and, in the fifth species, note values the style does
|
|
1051
|
+
* not write or a `durations` array that does not describe the counterpoint it
|
|
1052
|
+
* was given.
|
|
1053
|
+
* - `unpreparedDissonance`: a dissonance falls where the species allows none, or
|
|
1054
|
+
* is reached or left by leap where it must be passed through by step.
|
|
1055
|
+
* - `unresolvedSuspension`: a fourth-species suspension that does not fall by
|
|
1056
|
+
* step onto the following consonance.
|
|
1057
|
+
* - `illegalLeap`: a melodic leap the style forbids — either seventh, the
|
|
1058
|
+
* tritone, or anything wider than an octave.
|
|
1059
|
+
* - `battuta`: an octave or unison reached by contrary motion with the upper
|
|
1060
|
+
* voice leaping down.
|
|
1061
|
+
* - `missingCadence`: the exercise does not open or close on the formula its
|
|
1062
|
+
* species requires.
|
|
1063
|
+
* - `melodicShape`: the counterpoint is a poor line — it has no single climax,
|
|
1064
|
+
* leaps too often or too far one way, leaves a wide leap unanswered, outlines
|
|
1065
|
+
* a tritone, or repeats a note where the species keeps moving. The rationale
|
|
1066
|
+
* says which.
|
|
1067
|
+
*
|
|
1068
|
+
* @category Voicing & Counterpoint
|
|
1069
|
+
*/
|
|
1070
|
+
type PartWritingViolationKind = 'parallelFifth' | 'parallelOctave' | 'hiddenPerfect' | 'crossRelation' | 'voiceCrossing' | 'overlap' | 'spacing' | 'range' | 'unresolvedLeadingTone' | 'unresolvedSeventh' | 'augmentedMelodicInterval' | 'wrongRhythmicRatio' | 'unpreparedDissonance' | 'unresolvedSuspension' | 'illegalLeap' | 'battuta' | 'missingCadence' | 'melodicShape';
|
|
1071
|
+
/**
|
|
1072
|
+
* One broken rule, located in the progression and in the texture.
|
|
1073
|
+
*
|
|
1074
|
+
* @category Voicing & Counterpoint
|
|
1075
|
+
*/
|
|
1076
|
+
type PartWritingViolation = {
|
|
1077
|
+
/** The rule that was broken. */
|
|
1078
|
+
kind: PartWritingViolationKind;
|
|
1079
|
+
/**
|
|
1080
|
+
* The voices involved, by index into a voicing (0 = lowest). A rule about a
|
|
1081
|
+
* pair names both, ascending; a rule about a single line names one. A
|
|
1082
|
+
* `crossRelation` is the exception: it names the voice holding the earlier
|
|
1083
|
+
* note first, whichever is higher. In a species exercise there are only two
|
|
1084
|
+
* voices and they are named by role instead: 0 is the cantus firmus and 1 the
|
|
1085
|
+
* counterpoint, whichever lies above.
|
|
1086
|
+
*/
|
|
1087
|
+
voices: number[];
|
|
1088
|
+
/**
|
|
1089
|
+
* Index of the chord the motion starts on; in a species exercise, the index
|
|
1090
|
+
* into the counterpoint.
|
|
1091
|
+
*/
|
|
1092
|
+
fromIndex: number;
|
|
1093
|
+
/** Index of the chord it ends on; equal to `fromIndex` for a vertical rule. */
|
|
1094
|
+
toIndex: number;
|
|
1095
|
+
/** A short sentence naming the musical reason. */
|
|
1096
|
+
rationale: string;
|
|
1097
|
+
};
|
|
1098
|
+
/**
|
|
1099
|
+
* A chord realized as one spelled note per voice, in voice order (index 0 =
|
|
1100
|
+
* bass), matching the order {@link voiceChord} and {@link SATB_RANGES} use.
|
|
1101
|
+
* Pitches need not ascend; a crossing is a reportable violation.
|
|
1102
|
+
*
|
|
1103
|
+
* Every note must carry an octave: the rules measure real distances between
|
|
1104
|
+
* sounding pitches, which a bare pitch class does not have.
|
|
1105
|
+
*
|
|
1106
|
+
* @category Voicing & Counterpoint
|
|
1107
|
+
*/
|
|
1108
|
+
type SpelledVoicing = Note[];
|
|
1109
|
+
/**
|
|
1110
|
+
* Options controlling {@link checkPartWriting}.
|
|
1111
|
+
*
|
|
1112
|
+
* @category Voicing & Counterpoint
|
|
1113
|
+
*/
|
|
1114
|
+
type PartWritingOptions = {
|
|
1115
|
+
/**
|
|
1116
|
+
* Per-voice ranges, ascending (index 0 = lowest), against which the `range`
|
|
1117
|
+
* rule is judged. Defaults to {@link SATB_RANGES} for a four-voice exercise;
|
|
1118
|
+
* for any other voice count there is no conventional compass to assume, so
|
|
1119
|
+
* the rule is skipped unless ranges are given. Given ranges must cover every
|
|
1120
|
+
* voice of the widest chord, and each must be finite with `min` no greater
|
|
1121
|
+
* than `max`.
|
|
1122
|
+
*/
|
|
1123
|
+
ranges?: VoiceRange[];
|
|
1124
|
+
/**
|
|
1125
|
+
* Maximum spacing in semitones between adjacent upper voices. The bass-tenor
|
|
1126
|
+
* pair is exempt, as convention has it. Must be finite and non-negative.
|
|
1127
|
+
*
|
|
1128
|
+
* @defaultValue 12
|
|
1129
|
+
*/
|
|
1130
|
+
maxSpacing?: number;
|
|
1131
|
+
};
|
|
1132
|
+
/**
|
|
1133
|
+
* Spell a voicing given as MIDI pitches, so it can be checked by
|
|
1134
|
+
* {@link checkPartWriting}.
|
|
1135
|
+
*
|
|
1136
|
+
* Each pitch is named against the chord sounding under it and then the key, so a
|
|
1137
|
+
* chord tone takes the letter the degree it plays in that chord implies: the
|
|
1138
|
+
* third of a D major chord in C major spells F#, not Gb. The chord is passed
|
|
1139
|
+
* whole rather than by its root, so a chord carrying its own spelling names its
|
|
1140
|
+
* tones here exactly as {@link spellChord} names them — the German sixth keeps
|
|
1141
|
+
* the F# that resolves outward to the dominant. The octave is kept, since the
|
|
1142
|
+
* rules measure real distances.
|
|
1143
|
+
*
|
|
1144
|
+
* @param voicing MIDI pitches in voice order (index 0 = bass).
|
|
1145
|
+
* @param chord The chord sounding, supplying the enharmonic evidence.
|
|
1146
|
+
* @param key The key the exercise is written in.
|
|
1147
|
+
* @returns One spelled note per pitch, in the same order.
|
|
1148
|
+
* @example
|
|
1149
|
+
* ```ts
|
|
1150
|
+
* import { majorKey, makeChord, noteNames, spellVoicing } from '@libraz/libcantus';
|
|
1151
|
+
* noteNames(spellVoicing([50, 57, 66, 69], makeChord(2, 'maj'), majorKey(0)));
|
|
1152
|
+
* // ['D3', 'A3', 'F#4', 'A4'] — the third of D spells F# in C major
|
|
1153
|
+
* ```
|
|
1154
|
+
* @category Voicing & Counterpoint
|
|
1155
|
+
*/
|
|
1156
|
+
declare function spellVoicing(voicing: readonly number[], chord: Chord, key: SpelledKeyLike): SpelledVoicing;
|
|
1157
|
+
/**
|
|
1158
|
+
* Check a finished part-writing exercise and report every rule it breaks.
|
|
1159
|
+
*
|
|
1160
|
+
* The voicings are given one per chord, each with one spelled note per voice in
|
|
1161
|
+
* voice order (index 0 = bass), the order {@link voiceChord} and
|
|
1162
|
+
* {@link SATB_RANGES} already use. Notes must carry octaves. A crossing is
|
|
1163
|
+
* reported rather than rejected.
|
|
1164
|
+
*
|
|
1165
|
+
* Each chord is checked for voice crossing, over-wide spacing between adjacent
|
|
1166
|
+
* upper voices, and voices outside their range; each pair of consecutive chords
|
|
1167
|
+
* for parallel and hidden perfects, voice overlap, cross relations, augmented
|
|
1168
|
+
* melodic intervals, and unresolved tendency tones. Violations come back in
|
|
1169
|
+
* musical order: the rules inside a chord, then the rules taking it to the next.
|
|
1170
|
+
*
|
|
1171
|
+
* @param voicings One voicing per chord, in voice order, in spelled notes.
|
|
1172
|
+
* @param chords The chords those voicings realize, in the same order.
|
|
1173
|
+
* @param keyLike The key the exercise is written in; it names the leading tone.
|
|
1174
|
+
* @param opts Ranges and the upper-voice spacing limit. Both are validated
|
|
1175
|
+
* before any rule runs: an empty result has to mean that nothing was broken,
|
|
1176
|
+
* never that a rule could not be evaluated.
|
|
1177
|
+
* @returns Every violation found, in musical order; an empty array for a clean
|
|
1178
|
+
* exercise.
|
|
1179
|
+
* @throws If the two arrays differ in length, a note carries no octave, the
|
|
1180
|
+
* spacing limit is not a non-negative finite number, or the ranges are empty,
|
|
1181
|
+
* malformed, or too few for the voices being checked.
|
|
1182
|
+
* @example
|
|
1183
|
+
* ```ts
|
|
1184
|
+
* import { checkPartWriting, majorKey, makeChord, spellVoicing } from '@libraz/libcantus';
|
|
1185
|
+
* const key = majorKey(0);
|
|
1186
|
+
* const chords = [makeChord(0, 'maj'), makeChord(2, 'min')];
|
|
1187
|
+
* const voicings = [[48, 55, 64, 72], [50, 57, 65, 69]].map((pitches, i) =>
|
|
1188
|
+
* spellVoicing(pitches, chords[i] ?? chords[0], key),
|
|
1189
|
+
* );
|
|
1190
|
+
* const violations = checkPartWriting(voicings, chords, key);
|
|
1191
|
+
* violations.map((violation) => violation.kind); // ['parallelFifth']
|
|
1192
|
+
* violations[0]?.voices; // [0, 1]
|
|
1193
|
+
* ```
|
|
1194
|
+
* @category Voicing & Counterpoint
|
|
1195
|
+
*/
|
|
1196
|
+
declare function checkPartWriting(voicings: readonly SpelledVoicing[], chords: readonly Chord[], keyLike: KeyLike, opts?: PartWritingOptions): PartWritingViolation[];
|
|
1197
|
+
|
|
1198
|
+
/**
|
|
1199
|
+
* Transposing instruments: the fixed interval between the pitch a player reads
|
|
1200
|
+
* and the pitch the instrument sounds.
|
|
1201
|
+
*
|
|
1202
|
+
* The distance is a spelled interval, never a semitone count. A clarinet in A
|
|
1203
|
+
* sounds a minor third below what it reads, so a written C sounds A, a written
|
|
1204
|
+
* D sounds B, and a written D# sounds B#: the letter always moves by the
|
|
1205
|
+
* interval's diatonic number, where a bare count of three semitones would take
|
|
1206
|
+
* the last of those to C natural and lose the letter the part is written on.
|
|
1207
|
+
*
|
|
1208
|
+
* The octave is part of that interval rather than folded away into a pitch
|
|
1209
|
+
* class, so instruments pitched in the same key stay apart: the alto saxophone
|
|
1210
|
+
* sounds a major sixth lower, the baritone saxophone a major thirteenth (the
|
|
1211
|
+
* same key an octave further down), and the E flat clarinet a minor third
|
|
1212
|
+
* higher. The pure octave transposers — piccolo, double bass, contrabassoon,
|
|
1213
|
+
* guitar — are a perfect octave, a unison-class interval displaced by one
|
|
1214
|
+
* octave.
|
|
1215
|
+
*/
|
|
1216
|
+
|
|
1217
|
+
/**
|
|
1218
|
+
* The interval from a written pitch to the pitch the instrument sounds, one
|
|
1219
|
+
* entry per built-in instrument.
|
|
1220
|
+
*
|
|
1221
|
+
* Each value is an interval name as {@link parseInterval} reads it, in the
|
|
1222
|
+
* written-to-sounding direction: a leading `'-'` marks an instrument that
|
|
1223
|
+
* sounds below what it reads, which is most of them. A transposition wider than
|
|
1224
|
+
* an octave is named by its compound interval rather than reduced, because the
|
|
1225
|
+
* octave is exactly what separates the tenor saxophone from the soprano and the
|
|
1226
|
+
* baritone from the alto.
|
|
1227
|
+
*
|
|
1228
|
+
* @example
|
|
1229
|
+
* ```ts
|
|
1230
|
+
* import { TRANSPOSING_INSTRUMENTS } from '@libraz/libcantus';
|
|
1231
|
+
* TRANSPOSING_INSTRUMENTS.clarinetA; // '-m3' — sounds a minor third lower
|
|
1232
|
+
* TRANSPOSING_INSTRUMENTS.piccolo; // 'P8' — sounds an octave higher
|
|
1233
|
+
* ```
|
|
1234
|
+
* @category Pitch & Intervals
|
|
1235
|
+
*/
|
|
1236
|
+
declare const TRANSPOSING_INSTRUMENTS: Readonly<{
|
|
1237
|
+
clarinetBb: "-M2";
|
|
1238
|
+
trumpetBb: "-M2";
|
|
1239
|
+
sopranoSax: "-M2";
|
|
1240
|
+
tenorSax: "-M9";
|
|
1241
|
+
bassClarinet: "-M9";
|
|
1242
|
+
clarinetA: "-m3";
|
|
1243
|
+
hornF: "-P5";
|
|
1244
|
+
englishHorn: "-P5";
|
|
1245
|
+
clarinetEb: "m3";
|
|
1246
|
+
altoSax: "-M6";
|
|
1247
|
+
baritoneSax: "-M13";
|
|
1248
|
+
trumpetD: "M2";
|
|
1249
|
+
piccolo: "P8";
|
|
1250
|
+
doubleBass: "-P8";
|
|
1251
|
+
contrabassoon: "-P8";
|
|
1252
|
+
guitar: "-P8";
|
|
1253
|
+
}>;
|
|
1254
|
+
/**
|
|
1255
|
+
* The name of a built-in transposing instrument, as
|
|
1256
|
+
* {@link TRANSPOSING_INSTRUMENTS} keys them.
|
|
1257
|
+
*
|
|
1258
|
+
* @example
|
|
1259
|
+
* ```ts
|
|
1260
|
+
* import type { TransposingInstrumentName } from '@libraz/libcantus';
|
|
1261
|
+
* const part: TransposingInstrumentName = 'clarinetA';
|
|
1262
|
+
* ```
|
|
1263
|
+
* @category Pitch & Intervals
|
|
1264
|
+
*/
|
|
1265
|
+
type TransposingInstrumentName = keyof typeof TRANSPOSING_INSTRUMENTS;
|
|
1266
|
+
/**
|
|
1267
|
+
* A transposing instrument: one of the built-in names, or a spelled interval
|
|
1268
|
+
* for an instrument the table does not carry.
|
|
1269
|
+
*
|
|
1270
|
+
* An interval is read in the same written-to-sounding direction as the table,
|
|
1271
|
+
* so `'-M2'` is any instrument in B flat and `'P8'` any that sounds an octave
|
|
1272
|
+
* up. The names complete in an editor while any other string is still accepted,
|
|
1273
|
+
* which is what lets an instrument read from configuration go straight in.
|
|
1274
|
+
*
|
|
1275
|
+
* @example
|
|
1276
|
+
* ```ts
|
|
1277
|
+
* import type { TransposingInstrument } from '@libraz/libcantus';
|
|
1278
|
+
* const clarinet: TransposingInstrument = 'clarinetA';
|
|
1279
|
+
* const altoFlute: TransposingInstrument = '-P4';
|
|
1280
|
+
* ```
|
|
1281
|
+
* @category Pitch & Intervals
|
|
1282
|
+
*/
|
|
1283
|
+
type TransposingInstrument = TransposingInstrumentName | (string & {}) | Exclude<IntervalLike, string>;
|
|
1284
|
+
/**
|
|
1285
|
+
* The interval a transposing instrument sounds at, measured from what it reads.
|
|
1286
|
+
*
|
|
1287
|
+
* This is the table's own direction: the answer descends for an instrument that
|
|
1288
|
+
* sounds below the printed part, which is most of them. Applying it to a
|
|
1289
|
+
* written pitch is {@link toSoundingPitch}, and applying it to a concert key is
|
|
1290
|
+
* how a written key is read back as the key it sounds in.
|
|
1291
|
+
*
|
|
1292
|
+
* @param instrument A built-in instrument name, or an interval naming a
|
|
1293
|
+
* transposition the table does not carry.
|
|
1294
|
+
* @returns The written-to-sounding interval.
|
|
1295
|
+
* @throws If the value is neither a known instrument nor a spelled interval.
|
|
1296
|
+
* @example
|
|
1297
|
+
* ```ts
|
|
1298
|
+
* import { instrumentTransposition } from '@libraz/libcantus';
|
|
1299
|
+
* instrumentTransposition('clarinetA');
|
|
1300
|
+
* // { number: 3, quality: 'm', semitones: -3, descending: true }
|
|
1301
|
+
* instrumentTransposition('piccolo');
|
|
1302
|
+
* // { number: 8, quality: 'P', semitones: 12, descending: false }
|
|
1303
|
+
* ```
|
|
1304
|
+
* @category Pitch & Intervals
|
|
1305
|
+
*/
|
|
1306
|
+
declare function instrumentTransposition(instrument: TransposingInstrument): SpelledInterval;
|
|
1307
|
+
/**
|
|
1308
|
+
* The pitch an instrument sounds for a written note.
|
|
1309
|
+
*
|
|
1310
|
+
* The interval decides the letter, so the spelling of the part survives the
|
|
1311
|
+
* conversion: on a clarinet in A a written C sounds A, a written D sounds B,
|
|
1312
|
+
* and a written D# sounds B# — a semitone count alone could answer C natural
|
|
1313
|
+
* for that last one and lose the letter the part is written on. A note carrying
|
|
1314
|
+
* an octave moves register with it — a written C4 sounds A3 — while an
|
|
1315
|
+
* octave-less note stays octave-less, so a pure octave transposer leaves it
|
|
1316
|
+
* alone.
|
|
1317
|
+
*
|
|
1318
|
+
* @param note The written note, as the player reads it: a note name, a MIDI
|
|
1319
|
+
* number, note data, or a `Note`.
|
|
1320
|
+
* @param instrument A built-in instrument name, or an interval naming a
|
|
1321
|
+
* transposition the table does not carry.
|
|
1322
|
+
* @returns The sounding note, at concert pitch.
|
|
1323
|
+
* @throws If the note is malformed, or the instrument is neither a known name
|
|
1324
|
+
* nor a spelled interval.
|
|
1325
|
+
* @example
|
|
1326
|
+
* ```ts
|
|
1327
|
+
* import { formatNote, parseNote, toSoundingPitch } from '@libraz/libcantus';
|
|
1328
|
+
* formatNote(toSoundingPitch(parseNote('C4'), 'clarinetA')); // 'A3'
|
|
1329
|
+
* formatNote(toSoundingPitch('D#4', 'clarinetA')); // 'B#3'
|
|
1330
|
+
* formatNote(toSoundingPitch(parseNote('C4'), 'piccolo')); // 'C5'
|
|
1331
|
+
* ```
|
|
1332
|
+
* @category Pitch & Intervals
|
|
1333
|
+
*/
|
|
1334
|
+
declare function toSoundingPitch(note: NoteLike, instrument: TransposingInstrument): Note;
|
|
1335
|
+
/**
|
|
1336
|
+
* The note an instrument must read to sound a given concert pitch.
|
|
1337
|
+
*
|
|
1338
|
+
* The exact inverse of {@link toSoundingPitch} for every instrument: the same
|
|
1339
|
+
* interval applied the other way, so the letter and the octave both come back.
|
|
1340
|
+
* A concert A3 is written C4 for a clarinet in A, and a concert E flat 3 is
|
|
1341
|
+
* written C4 for an alto saxophone but C5 for a baritone saxophone, which reads
|
|
1342
|
+
* the same key an octave lower.
|
|
1343
|
+
*
|
|
1344
|
+
* @param note The sounding note, at concert pitch: a note name, a MIDI number,
|
|
1345
|
+
* note data, or a `Note`.
|
|
1346
|
+
* @param instrument A built-in instrument name, or an interval naming a
|
|
1347
|
+
* transposition the table does not carry.
|
|
1348
|
+
* @returns The written note, as the player reads it.
|
|
1349
|
+
* @throws If the note is malformed, or the instrument is neither a known name
|
|
1350
|
+
* nor a spelled interval.
|
|
1351
|
+
* @example
|
|
1352
|
+
* ```ts
|
|
1353
|
+
* import { formatNote, parseNote, toWrittenPitch } from '@libraz/libcantus';
|
|
1354
|
+
* formatNote(toWrittenPitch(parseNote('A3'), 'clarinetA')); // 'C4'
|
|
1355
|
+
* formatNote(toWrittenPitch('Eb3', 'altoSax')); // 'C4'
|
|
1356
|
+
* formatNote(toWrittenPitch(parseNote('Eb3'), 'baritoneSax')); // 'C5'
|
|
1357
|
+
* ```
|
|
1358
|
+
* @category Pitch & Intervals
|
|
1359
|
+
*/
|
|
1360
|
+
declare function toWrittenPitch(note: NoteLike, instrument: TransposingInstrument): Note;
|
|
1361
|
+
|
|
1362
|
+
export { instrumentTransposition as B, isSignatureKey as D, keyFromFifths as E, keySignatureFifths as F, parseChordSymbol as G, scaleMatchesChord as H, scaleSystemOf as I, scalesForChanges as J, spellVoicing as L, supportsFunctionalHarmony as M, toSoundingPitch as N, toWrittenPitch as O, transposeChordSymbol as Q, tryParseChordSymbol as R, SATB_RANGES as S, TRANSPOSING_INSTRUMENTS as T, voiceChord as U, voiceChordStyled as W, voiceIndependence as X, voiceProgression as Y, SCALE_SYSTEMS as g, availableTensions as t, avoidNotes as u, checkPartWriting as v, checkSpecies as w, chordScaleReport as x, chordScales as y, formatChordSymbol as z };
|
|
1363
|
+
export type { AvailableTensionsOptions as A, ChordScaleMatch as C, KeyMode as K, PartWritingOptions as P, VoiceIndependenceOptions as V, AvoidNoteUse as a, AvoidNotesOptions as b, ChordScaleReportEntry as c, ChordSymbolOptions as d, PartWritingViolation as e, PartWritingViolationKind as f, ScaleChoice as h, ScaleSystem as i, Species as j, SpeciesOptions as k, SpelledVoicing as l, StyledVoicingOptions as m, TransposingInstrument as n, TransposingInstrumentName as o, VoiceIndependenceReport as p, VoiceRange as q, VoicingOptions as r, VoicingStyle as s };
|