@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,2599 @@
|
|
|
1
|
+
import { b as MeterLike, T as TimeSignature, c as MeterMap } from './index-wE8SecK5.js';
|
|
2
|
+
import { c as ChordLike, K as KeyLike, i as ChordToneRole, r as SpelledKeyLike, b as Chord, n as ResolvedKey, j as KeyRelation, e as ChordSegment, V as VoiceSnapshot, g as ChordSpan } from './coerce-Cr9AZsTY.js';
|
|
3
|
+
import { h as NoteEvent, e as KeyScale, S as SpelledInterval } from './index-C9MYbuKS.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* The vocabulary the analyze layer explains itself in.
|
|
7
|
+
*
|
|
8
|
+
* `analyzeVoice` has always returned a short `rationale` beside the labels it
|
|
9
|
+
* assigns; the chord, numeral, cadence and key readings say the same kind of
|
|
10
|
+
* thing about a larger unit. One vocabulary keeps a rationale readable wherever
|
|
11
|
+
* it comes from: the conclusion first, a colon, then the fact it rests on, as a
|
|
12
|
+
* phrase rather than a sentence.
|
|
13
|
+
*
|
|
14
|
+
* The reading that was turned down is worth as much to a reader arguing with the
|
|
15
|
+
* result as the one that was kept, so every entry point that ranks readings can
|
|
16
|
+
* report them in the one shape below.
|
|
17
|
+
*/
|
|
18
|
+
/**
|
|
19
|
+
* A reading that was considered and rejected, and why it lost.
|
|
20
|
+
*
|
|
21
|
+
* @category Arrangement & Analysis
|
|
22
|
+
*/
|
|
23
|
+
type RejectedCandidate = {
|
|
24
|
+
/** The rejected reading, named the way the accepted one is named. */
|
|
25
|
+
label: string;
|
|
26
|
+
/** Why the accepted reading was preferred over this one. */
|
|
27
|
+
reason: string;
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Key-profile vectors for {@link detectKey}.
|
|
32
|
+
*
|
|
33
|
+
* A key profile is a 12-entry vector indexed from the tonic (0 = tonic, 1 = flat
|
|
34
|
+
* second, ... 11 = major seventh) giving how strongly each chromatic degree is
|
|
35
|
+
* expected to sound in that key. Ranking a candidate key means rotating its
|
|
36
|
+
* profile onto the candidate tonic and correlating it with the pitch-class
|
|
37
|
+
* distribution of the music, which is what separates a key from its relative:
|
|
38
|
+
* C major and A minor contain the same seven pitch classes, but they expect the
|
|
39
|
+
* weight to fall on different degrees.
|
|
40
|
+
*
|
|
41
|
+
* The published vectors below are transcribed from their sources and are not
|
|
42
|
+
* tuned for this library; a citation accompanies each so a reader can check the
|
|
43
|
+
* digits.
|
|
44
|
+
*/
|
|
45
|
+
/**
|
|
46
|
+
* A pair of 12-entry key profiles, one per mode, each indexed from its own
|
|
47
|
+
* tonic (index 0 = tonic, 1 = flat second, ... 11 = major seventh).
|
|
48
|
+
*
|
|
49
|
+
* @category Recognition
|
|
50
|
+
*/
|
|
51
|
+
type KeyProfilePair = {
|
|
52
|
+
/** Degree weights for a major candidate, indexed from the major tonic. */
|
|
53
|
+
major: readonly number[];
|
|
54
|
+
/** Degree weights for a minor candidate, indexed from the minor tonic. */
|
|
55
|
+
minor: readonly number[];
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* Name of a built-in key profile accepted by {@link DetectKeyOptions.profile}.
|
|
59
|
+
*
|
|
60
|
+
* @category Recognition
|
|
61
|
+
*/
|
|
62
|
+
type KeyProfileName = 'krumhansl' | 'temperley' | 'flat';
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Borrowed chords (modal interchange) and the Neapolitan.
|
|
66
|
+
*
|
|
67
|
+
* Roots are pitch classes measured against the key tonic, so borrowed and
|
|
68
|
+
* chromatic chords are handled by their semitone offset rather than requiring a
|
|
69
|
+
* spelled key signature.
|
|
70
|
+
*/
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The origin of a recognized non-diatonic chord, or null when none applies.
|
|
74
|
+
*
|
|
75
|
+
* @category Functional Harmony
|
|
76
|
+
*/
|
|
77
|
+
type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
|
|
78
|
+
/**
|
|
79
|
+
* Whether a chord is borrowed from the parallel mode (modal interchange).
|
|
80
|
+
*
|
|
81
|
+
* True when the chord is not diatonic to `key` but is diatonic to its
|
|
82
|
+
* {@link parallelKeyOf | parallel key} — e.g. iv, bVI, or bVII in a major key, or the Picardy
|
|
83
|
+
* tonic and major IV in a minor key — and true for the Neapolitan, which is
|
|
84
|
+
* counted as a borrowing of its own even though it belongs to neither parallel
|
|
85
|
+
* mode. Two non-diatonic families are excluded: any other chord diatonic to
|
|
86
|
+
* neither mode (those are chromatic, not borrowed), and, in a minor key, chords
|
|
87
|
+
* explained by the altered minor forms (the major dominant and
|
|
88
|
+
* raised-leading-tone chords), which are in-key alterations rather than
|
|
89
|
+
* interchange even though they happen to fit the parallel major.
|
|
90
|
+
*
|
|
91
|
+
* @param chord The chord to test, as a chord symbol, chord data, or a `Chord`.
|
|
92
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
93
|
+
* @returns True if the chord is borrowed from the parallel mode.
|
|
94
|
+
* @category Functional Harmony
|
|
95
|
+
*/
|
|
96
|
+
declare function isBorrowedChord(chord: ChordLike, key: KeyLike): boolean;
|
|
97
|
+
/**
|
|
98
|
+
* Identify where a non-diatonic chord comes from.
|
|
99
|
+
*
|
|
100
|
+
* The Neapolitan (major triad on b2 of a key that does not have that degree
|
|
101
|
+
* already) is recognized first, since it sits outside both parallel modes;
|
|
102
|
+
* parallel-mode borrowing follows the {@link isBorrowedChord} rules. Diatonic
|
|
103
|
+
* chords and altered-minor chords, and unrecognized chromatic chords all yield
|
|
104
|
+
* null.
|
|
105
|
+
*
|
|
106
|
+
* @param chord The chord to classify, as a chord symbol, chord data, or a
|
|
107
|
+
* `Chord`.
|
|
108
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
109
|
+
* @returns The borrowing source, or null.
|
|
110
|
+
* @category Functional Harmony
|
|
111
|
+
*/
|
|
112
|
+
declare function borrowedSource(chord: ChordLike, key: KeyLike): BorrowedSource;
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Cadence detection between two successive chords.
|
|
116
|
+
*
|
|
117
|
+
* Roots are pitch classes measured against the key tonic, so borrowed and
|
|
118
|
+
* chromatic chords are handled by their semitone offset rather than requiring a
|
|
119
|
+
* spelled key signature.
|
|
120
|
+
*/
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* The named cadence types {@link detectCadence} classifies a chord pair as.
|
|
124
|
+
*
|
|
125
|
+
* @category Functional Harmony
|
|
126
|
+
*/
|
|
127
|
+
declare const CADENCE_TYPES: readonly ["authentic", "plagal", "half", "deceptive", "phrygian", "modal"];
|
|
128
|
+
/**
|
|
129
|
+
* The cadence a chord pair forms.
|
|
130
|
+
*
|
|
131
|
+
* `'phrygian'` and `'modal'` are the two named species: the first is a
|
|
132
|
+
* specific half cadence and is reported in place of `'half'`, the second is
|
|
133
|
+
* the bVII-to-I arrival that no common-practice type covers. Code counting
|
|
134
|
+
* half cadences has to count `'phrygian'` alongside `'half'`.
|
|
135
|
+
*
|
|
136
|
+
* @category Functional Harmony
|
|
137
|
+
*/
|
|
138
|
+
type CadenceType = (typeof CADENCE_TYPES)[number];
|
|
139
|
+
/**
|
|
140
|
+
* A recognized cadence, with the voice-leading facts its reading rests on.
|
|
141
|
+
*
|
|
142
|
+
* @category Functional Harmony
|
|
143
|
+
*/
|
|
144
|
+
type CadenceResult = {
|
|
145
|
+
/** The cadence the chord pair forms, or null when it forms none. */
|
|
146
|
+
type: CadenceType | null;
|
|
147
|
+
/**
|
|
148
|
+
* How conclusive an authentic cadence is: `'perfect'` when it is a PAC,
|
|
149
|
+
* `'imperfect'` when it is an IAC.
|
|
150
|
+
*
|
|
151
|
+
* Null for every other cadence type — the distinction is only defined for the
|
|
152
|
+
* authentic cadence — and null for an authentic cadence whose soprano is
|
|
153
|
+
* unknown, which is the case whenever no `voicing` is given.
|
|
154
|
+
*/
|
|
155
|
+
strength: 'perfect' | 'imperfect' | null;
|
|
156
|
+
/**
|
|
157
|
+
* The role the final chord's highest sounding pitch plays in that chord.
|
|
158
|
+
*
|
|
159
|
+
* Omitted when no `voicing` was given, and when the top voice is a tension
|
|
160
|
+
* with no basic chord-tone role.
|
|
161
|
+
*/
|
|
162
|
+
soprano?: ChordToneRole;
|
|
163
|
+
/**
|
|
164
|
+
* True when both chords stand on their own root — the inversion condition a
|
|
165
|
+
* perfect authentic cadence has to meet.
|
|
166
|
+
*/
|
|
167
|
+
rootPosition: boolean;
|
|
168
|
+
/**
|
|
169
|
+
* True when the dominant resolved onto an inverted tonic (V to I6 and its
|
|
170
|
+
* relatives) instead of the root-position arrival it prepared, so the
|
|
171
|
+
* cadential weight is withheld even though the type still holds.
|
|
172
|
+
*/
|
|
173
|
+
evaded: boolean;
|
|
174
|
+
/**
|
|
175
|
+
* Why the pair reads this way: the motion the type rests on, what graded an
|
|
176
|
+
* authentic cadence, and what a null type failed to be. Always present, in
|
|
177
|
+
* the phrasing {@link analyzeVoice} uses for a note.
|
|
178
|
+
*/
|
|
179
|
+
rationale: string;
|
|
180
|
+
/**
|
|
181
|
+
* The cadences that were considered and rejected, empty unless
|
|
182
|
+
* {@link DetectCadenceOptions.alternatives} asked for them.
|
|
183
|
+
*
|
|
184
|
+
* These are the near misses — the readings a condition or two away from
|
|
185
|
+
* holding — rather than every type that did not fire, which for most pairs
|
|
186
|
+
* would be all of them.
|
|
187
|
+
*/
|
|
188
|
+
alternatives: RejectedCandidate[];
|
|
189
|
+
};
|
|
190
|
+
/**
|
|
191
|
+
* Options for {@link detectCadence}.
|
|
192
|
+
*
|
|
193
|
+
* @category Functional Harmony
|
|
194
|
+
*/
|
|
195
|
+
type DetectCadenceOptions = {
|
|
196
|
+
/**
|
|
197
|
+
* The pitches actually sounding, as MIDI note numbers: the penultimate
|
|
198
|
+
* chord's voicing first, then the final chord's.
|
|
199
|
+
*
|
|
200
|
+
* The lowest pitch of each is its bass and so decides inversion, overriding
|
|
201
|
+
* whatever the chords' own `bassPc` says; the highest pitch of the final
|
|
202
|
+
* chord is the soprano. Without a voicing the soprano is unknown, and a
|
|
203
|
+
* perfect authentic cadence cannot be told from an imperfect one.
|
|
204
|
+
*/
|
|
205
|
+
voicing?: [number[], number[]];
|
|
206
|
+
/**
|
|
207
|
+
* Report the cadences this pair came close to forming and why each was
|
|
208
|
+
* turned down.
|
|
209
|
+
*
|
|
210
|
+
* Off by default: the rationale is built from facts the classification
|
|
211
|
+
* already established, while a rival has to be phrased against conditions
|
|
212
|
+
* that did not fire, and most callers read the type only.
|
|
213
|
+
*
|
|
214
|
+
* @defaultValue false
|
|
215
|
+
*/
|
|
216
|
+
alternatives?: boolean;
|
|
217
|
+
/**
|
|
218
|
+
* The chord before `from`, which is what tells a cadential six-four from an
|
|
219
|
+
* inverted tonic.
|
|
220
|
+
*
|
|
221
|
+
* A dominant reached from the tonic triad standing on its own bass was
|
|
222
|
+
* already sounding when that six-four did, so the cadence began there. Only
|
|
223
|
+
* the chord before the dominant settles that, and a caller reading a pair at
|
|
224
|
+
* a time has it to hand; without it the pair is classified on its own, as
|
|
225
|
+
* before.
|
|
226
|
+
*
|
|
227
|
+
* Accepted as a chord symbol, chord data, or a `Chord`.
|
|
228
|
+
*/
|
|
229
|
+
approach?: ChordLike;
|
|
230
|
+
};
|
|
231
|
+
/**
|
|
232
|
+
* Classify the cadence formed by moving from one chord to the next.
|
|
233
|
+
*
|
|
234
|
+
* - authentic: V (dominant a fifth above the tonic) to I
|
|
235
|
+
* - plagal: IV, the chord on the key's own fourth degree, to I
|
|
236
|
+
* - modal: bVII to I, the cadence of rock and modal writing
|
|
237
|
+
* - deceptive: V to the key's own submediant, plus the borrowed bVI of a major
|
|
238
|
+
* key
|
|
239
|
+
* - phrygian: iv6 to V of a minor key, the half cadence whose bass falls a
|
|
240
|
+
* semitone from b6 to 5
|
|
241
|
+
* - half: any other chord than the dominant itself to V, the cadential six-four
|
|
242
|
+
* standing on the dominant's own bass included
|
|
243
|
+
*
|
|
244
|
+
* These are read as scale degrees rather than as semitone distances, so a mode
|
|
245
|
+
* cadences from and onto the degrees it actually has: the deceptive arrival of
|
|
246
|
+
* dorian is a major sixth above the tonic and that of phrygian a minor sixth,
|
|
247
|
+
* and the subdominant a plagal cadence falls from is the tritone above the
|
|
248
|
+
* tonic in lydian. The two borrowed types are the exception, and are stated as
|
|
249
|
+
* the fixed offsets they name: `modal` is the flattened seventh whatever the
|
|
250
|
+
* key writes on that degree, and the Phrygian bass falls from the lowered
|
|
251
|
+
* submediant. A half cadence normally rests on the major third that carries
|
|
252
|
+
* the leading tone, but where the key's own dominant has no leading tone — the
|
|
253
|
+
* modal `v` of dorian, mixolydian and the pop writing built on them — the
|
|
254
|
+
* arrival's own third suffices as long as the key contains it. That relaxation
|
|
255
|
+
* belongs to the modes alone: a borrowed minor `v` in a major key is no half
|
|
256
|
+
* cadence, and neither is the `v` of a minor key, which cadences through the
|
|
257
|
+
* raised seventh it writes as an accidental rather than in its scale.
|
|
258
|
+
*
|
|
259
|
+
* A static V-to-V repeat with no root motion is not a cadence and yields a null
|
|
260
|
+
* type. The tonic six-four resolving onto the dominant it stands on is a half
|
|
261
|
+
* cadence, and the most ordinary one there is: `I - I64 - V` closes the
|
|
262
|
+
* antecedent of a period, and the six-four is a double appoggiatura over the
|
|
263
|
+
* dominant's own bass rather than a chord that keeps the motion going. Where
|
|
264
|
+
* that dominant goes on to resolve, the pair and the resolution are one event —
|
|
265
|
+
* passing the six-four as `approach` when the dominant is the `from` chord is
|
|
266
|
+
* what lets it be reported as one, with the type and the beat still the
|
|
267
|
+
* dominant's resolution while the `rationale` says the cadence began at the
|
|
268
|
+
* six-four. A six-four the bass leaves instead (`IV-I64-IV`, or a neighbouring
|
|
269
|
+
* one over the tonic) is an ordinary inverted tonic and is read as one.
|
|
270
|
+
*
|
|
271
|
+
* An authentic cadence is graded perfect or imperfect. Perfect takes the
|
|
272
|
+
* dominant to the tonic with both chords in root position and the tonic in the
|
|
273
|
+
* soprano; anything else authentic is imperfect, including the leading-tone
|
|
274
|
+
* cadence, which has no dominant root to stand on. Only a `voicing` names the
|
|
275
|
+
* soprano, so without one the grade is null — the pair could still be either,
|
|
276
|
+
* and reporting perfect would be a guess.
|
|
277
|
+
*
|
|
278
|
+
* The `rationale` says which motion the reading rests on, including for a pair
|
|
279
|
+
* that cadences not at all; `alternatives` is empty unless asked for, and then
|
|
280
|
+
* names the cadences the pair came close to forming.
|
|
281
|
+
*
|
|
282
|
+
* @param from The penultimate chord, as a chord symbol, chord data, or a
|
|
283
|
+
* `Chord`.
|
|
284
|
+
* @param to The final chord, in any of the same forms.
|
|
285
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
286
|
+
* @param opts Voice-leading detail, the chord before `from`, and whether to
|
|
287
|
+
* collect the rejected readings; see {@link DetectCadenceOptions}.
|
|
288
|
+
* @returns The cadence, its strength, and the facts behind them.
|
|
289
|
+
* @example
|
|
290
|
+
* ```ts
|
|
291
|
+
* import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
|
|
292
|
+
* detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0));
|
|
293
|
+
* // { type: 'authentic', strength: null, rootPosition: true, evaded: false, ... }
|
|
294
|
+
* detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0), {
|
|
295
|
+
* voicing: [[55, 62, 71], [48, 64, 72]],
|
|
296
|
+
* });
|
|
297
|
+
* // { type: 'authentic', strength: 'perfect', soprano: 'root', ... }
|
|
298
|
+
* const sixFour = detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0), {
|
|
299
|
+
* approach: makeChord(0, 'maj', 7), // C/G, the cadential six-four
|
|
300
|
+
* });
|
|
301
|
+
* sixFour.type; // 'authentic'
|
|
302
|
+
* // The rationale says where the cadence began.
|
|
303
|
+
* sixFour.rationale?.includes('cadential six-four'); // true
|
|
304
|
+
* ```
|
|
305
|
+
* @category Functional Harmony
|
|
306
|
+
*/
|
|
307
|
+
declare function detectCadence(from: ChordLike, to: ChordLike, key: KeyLike, opts?: DetectCadenceOptions): CadenceResult;
|
|
308
|
+
|
|
309
|
+
/**
|
|
310
|
+
* Roman-numeral parsing and formatting.
|
|
311
|
+
*
|
|
312
|
+
* The {@link ROMAN_STYLE} table is the single source of truth for both
|
|
313
|
+
* directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
|
|
314
|
+
* inverses by construction. The chromatic chords no numeral can spell — the
|
|
315
|
+
* augmented sixths, and the Neapolitan under its figured name — are matched as
|
|
316
|
+
* whole symbols beside that table.
|
|
317
|
+
*/
|
|
318
|
+
|
|
319
|
+
/**
|
|
320
|
+
* Build the chord denoted by a Roman numeral in a key.
|
|
321
|
+
*
|
|
322
|
+
* Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
|
|
323
|
+
* suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
|
|
324
|
+
* (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
|
|
325
|
+
* (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
|
|
326
|
+
* whose root becomes a local major tonic for the applied chord. Inverted chords
|
|
327
|
+
* carry a `bassPc`.
|
|
328
|
+
*
|
|
329
|
+
* The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
|
|
330
|
+
* `m7b5`), since no half-diminished triad exists. Extension and added-tone
|
|
331
|
+
* suffixes are the canonical case-sensitive forms emitted by
|
|
332
|
+
* {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
|
|
333
|
+
* `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
|
|
334
|
+
* `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
|
|
335
|
+
* `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
|
|
336
|
+
* A figure string that is neither a recognized inversion nor a supported
|
|
337
|
+
* quality suffix throws rather than silently degrading to a triad.
|
|
338
|
+
*
|
|
339
|
+
* Four chromatic chords are named rather than numbered, and are accepted as
|
|
340
|
+
* whole symbols: the augmented sixths `It6`, `Fr6` and `Ger6` (also written
|
|
341
|
+
* `Ger65`), all three on the lowered submediant in the bass, and `N6` for the
|
|
342
|
+
* first-inversion Neapolitan, which builds exactly the chord `bII6` does.
|
|
343
|
+
* Each may be applied to a degree like any other numeral, so `Ger6/V` is the
|
|
344
|
+
* German sixth of the dominant.
|
|
345
|
+
*
|
|
346
|
+
* @param text The Roman numeral.
|
|
347
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
348
|
+
* @returns The chord.
|
|
349
|
+
* @throws If `key` names no key, `text` is not a string, or it is no numeral
|
|
350
|
+
* this reads.
|
|
351
|
+
* @example
|
|
352
|
+
* ```ts
|
|
353
|
+
* import { romanToChord, majorKey } from '@libraz/libcantus';
|
|
354
|
+
* romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
|
|
355
|
+
* romanToChord('Ger6', majorKey(0)); // Ab C Eb F#, bass Ab
|
|
356
|
+
* ```
|
|
357
|
+
* @category Functional Harmony
|
|
358
|
+
*/
|
|
359
|
+
declare function romanToChord(text: string, key: SpelledKeyLike): Chord;
|
|
360
|
+
/**
|
|
361
|
+
* Options for {@link chordToRoman}.
|
|
362
|
+
*
|
|
363
|
+
* @category Functional Harmony
|
|
364
|
+
*/
|
|
365
|
+
type ChordToRomanOptions = {
|
|
366
|
+
/**
|
|
367
|
+
* Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
|
|
368
|
+
* instead of naming its root against the home key (`II7`, `#ivo7`).
|
|
369
|
+
*
|
|
370
|
+
* Off by default: naming the root is always a correct spelling, whereas
|
|
371
|
+
* whether a chromatic dominant is genuinely applied is a reading only the
|
|
372
|
+
* caller can make. Turning it on names the chords {@link secondaryDominant}
|
|
373
|
+
* builds as the applied numerals they are, except in four cases, where the
|
|
374
|
+
* numeral names the root against the home key as it does with this off:
|
|
375
|
+
*
|
|
376
|
+
* - The target degree carries no perfect fifth: nothing tonicizes a
|
|
377
|
+
* diminished triad, so a chord over the seventh degree of a major key stays
|
|
378
|
+
* `#IV7` rather than becoming a numeral no harmony text writes.
|
|
379
|
+
* - The target is the tonic, which its own dominant points at: `V7` is the
|
|
380
|
+
* key's dominant and `V/I` is a numeral no harmony text writes either.
|
|
381
|
+
* - The chord is diatonic to the key, which keeps the function of its degree
|
|
382
|
+
* rather than tonicizing another. `G7` is `VII7` in A minor and `I7` in C
|
|
383
|
+
* mixolydian, not `V7/III` and `V7/IV`.
|
|
384
|
+
* - The chord is borrowed from the parallel mode, which sounds its own degree:
|
|
385
|
+
* the Picardy tonic and the major IV of a minor key are `I` and `IV`, not
|
|
386
|
+
* `V/iv` and `V/VII`.
|
|
387
|
+
*/
|
|
388
|
+
applied?: boolean;
|
|
389
|
+
/**
|
|
390
|
+
* Render a first-inversion Neapolitan under its figured name `N6` instead of
|
|
391
|
+
* the numeral `bII6`.
|
|
392
|
+
*
|
|
393
|
+
* Off by default, for the opposite reason to `applied`: both spellings name
|
|
394
|
+
* the same chord and `bII6` is already correct, so which one to write is a
|
|
395
|
+
* house-style choice rather than an analysis. `romanToChord` accepts either
|
|
396
|
+
* whatever this is set to. The augmented sixths need no such switch — no
|
|
397
|
+
* numeral spells them at all, so they always render as `It6`, `Fr6`
|
|
398
|
+
* and `Ger6`.
|
|
399
|
+
*/
|
|
400
|
+
neapolitan?: boolean;
|
|
401
|
+
};
|
|
402
|
+
/**
|
|
403
|
+
* Render a chord as a Roman numeral relative to a key.
|
|
404
|
+
*
|
|
405
|
+
* Diatonic roots take their scale-degree numeral directly, so numerals are
|
|
406
|
+
* correct in both major and minor keys (and any custom scale). The quality
|
|
407
|
+
* selects the case and suffix; chromatic roots receive a flat/sharp spelling by
|
|
408
|
+
* convention. A key that is not heptatonic has no numeral of its own for every
|
|
409
|
+
* degree, so its roots are named against its parallel major.
|
|
410
|
+
*
|
|
411
|
+
* When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
|
|
412
|
+
* (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
|
|
413
|
+
* chords; added-tone and extended qualities have no lossless figure and render
|
|
414
|
+
* in root position instead (the bass is dropped, pitch classes are preserved).
|
|
415
|
+
*
|
|
416
|
+
* A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
|
|
417
|
+
* `C/D` — is likewise dropped, and the numeral names the upper chord alone.
|
|
418
|
+
* Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
|
|
419
|
+
* is no unambiguous way to write such a bass; a caller that must keep it should
|
|
420
|
+
* read `chord.bassPc` alongside the numeral.
|
|
421
|
+
*
|
|
422
|
+
* A chord sounding one of the augmented sixths over an explicit bass on the
|
|
423
|
+
* lowered submediant renders as `It6`, `Fr6` or `Ger6`, since no numeral names
|
|
424
|
+
* those chords; see {@link augmentedSixthKind} for exactly when that applies.
|
|
425
|
+
* That reading is made against the key as written, because what separates an
|
|
426
|
+
* augmented sixth from the seventh chord it sounds like is its letters: the
|
|
427
|
+
* German sixth of Ab minor is named from the Fb Ab Cb D it is written with, not
|
|
428
|
+
* from the letters those pitch classes take once the key has been respelled as
|
|
429
|
+
* a G# minor.
|
|
430
|
+
*
|
|
431
|
+
* @param chord The chord to name, as a chord symbol, chord data, or a `Chord`.
|
|
432
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
433
|
+
* @param opts `applied` renders tonicizing chords as `V7/V`-style numerals;
|
|
434
|
+
* `neapolitan` renders a first-inversion Neapolitan as `N6`.
|
|
435
|
+
* @returns The Roman numeral string.
|
|
436
|
+
* @example
|
|
437
|
+
* ```ts
|
|
438
|
+
* import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
|
|
439
|
+
* chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
|
|
440
|
+
* chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
|
|
441
|
+
* ```
|
|
442
|
+
* @see {@link explainRoman} for the same numeral with the reasoning behind it.
|
|
443
|
+
* @category Functional Harmony
|
|
444
|
+
*/
|
|
445
|
+
declare function chordToRoman(chord: ChordLike, key: KeyLike, opts?: ChordToRomanOptions): string;
|
|
446
|
+
/**
|
|
447
|
+
* A numeral with the reasoning behind it.
|
|
448
|
+
*
|
|
449
|
+
* @category Functional Harmony
|
|
450
|
+
*/
|
|
451
|
+
type RomanExplanation = {
|
|
452
|
+
/** The numeral, exactly as {@link chordToRoman} renders it. */
|
|
453
|
+
roman: string;
|
|
454
|
+
/** How the numeral was arrived at: the degree, the quality, and the bass. */
|
|
455
|
+
rationale: string;
|
|
456
|
+
/**
|
|
457
|
+
* The spellings the options turned down, empty unless the `alternatives`
|
|
458
|
+
* option of {@link ExplainRomanOptions} asked for them.
|
|
459
|
+
*/
|
|
460
|
+
alternatives: RejectedCandidate[];
|
|
461
|
+
};
|
|
462
|
+
/**
|
|
463
|
+
* Options for {@link explainRoman}: {@link ChordToRomanOptions} plus the switch
|
|
464
|
+
* for the rival spellings.
|
|
465
|
+
*
|
|
466
|
+
* @category Functional Harmony
|
|
467
|
+
*/
|
|
468
|
+
type ExplainRomanOptions = ChordToRomanOptions & {
|
|
469
|
+
/**
|
|
470
|
+
* Report the numerals the other option settings would have rendered, and why
|
|
471
|
+
* this one was rendered instead.
|
|
472
|
+
*
|
|
473
|
+
* Off by default: each rival costs a further rendering pass, and a caller
|
|
474
|
+
* that only wants the numeral explained should not pay for the ones it did
|
|
475
|
+
* not get.
|
|
476
|
+
*
|
|
477
|
+
* @defaultValue false
|
|
478
|
+
*/
|
|
479
|
+
alternatives?: boolean;
|
|
480
|
+
};
|
|
481
|
+
/**
|
|
482
|
+
* Render a chord as a Roman numeral and say how the numeral was arrived at.
|
|
483
|
+
*
|
|
484
|
+
* The numeral is exactly what {@link chordToRoman} returns for the same
|
|
485
|
+
* arguments — this is that function with its reasoning attached, for teaching
|
|
486
|
+
* material and for any interface whose users argue with the analysis. The
|
|
487
|
+
* rationale names the degree the root was spelled as, the quality that set the
|
|
488
|
+
* numeral's case and suffix, and what became of the bass, including the two
|
|
489
|
+
* cases where a bass exists and no numeral can carry it.
|
|
490
|
+
*
|
|
491
|
+
* @param chord The chord to name, as a chord symbol, chord data, or a `Chord`.
|
|
492
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
493
|
+
* @param opts The rendering options of {@link chordToRoman}, plus
|
|
494
|
+
* `alternatives` to collect the spellings they turned down.
|
|
495
|
+
* @returns The numeral, its rationale, and the rejected spellings.
|
|
496
|
+
* @example
|
|
497
|
+
* ```ts
|
|
498
|
+
* import { explainRoman, makeChord, majorKey } from '@libraz/libcantus';
|
|
499
|
+
* explainRoman(makeChord(7, 'dom7'), majorKey(0)).rationale;
|
|
500
|
+
* // 'V7: the root is the fifth degree of the key, the case and suffix come from the dom7 quality, and the chord stands on its own root'
|
|
501
|
+
* const applied = explainRoman(makeChord(2, 'dom7'), majorKey(0), { alternatives: true });
|
|
502
|
+
* applied.alternatives?.map((rejected) => rejected.label); // ['V7/V']
|
|
503
|
+
* ```
|
|
504
|
+
* @category Functional Harmony
|
|
505
|
+
*/
|
|
506
|
+
declare function explainRoman(chord: ChordLike, key: KeyLike, opts?: ExplainRomanOptions): RomanExplanation;
|
|
507
|
+
|
|
508
|
+
/**
|
|
509
|
+
* Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
|
|
510
|
+
* mirroring, and full chord analysis.
|
|
511
|
+
*
|
|
512
|
+
* Roots are pitch classes measured against the key tonic, so borrowed and
|
|
513
|
+
* chromatic chords are handled by their semitone offset rather than requiring a
|
|
514
|
+
* spelled key signature.
|
|
515
|
+
*/
|
|
516
|
+
|
|
517
|
+
/**
|
|
518
|
+
* The harmonic functions {@link functionOf} can assign.
|
|
519
|
+
*
|
|
520
|
+
* @category Functional Harmony
|
|
521
|
+
*/
|
|
522
|
+
declare const HARMONIC_FUNCTIONS: readonly ["tonic", "subdominant", "dominant"];
|
|
523
|
+
/**
|
|
524
|
+
* The three broad harmonic functions of tonal music.
|
|
525
|
+
*
|
|
526
|
+
* @category Functional Harmony
|
|
527
|
+
*/
|
|
528
|
+
type HarmonicFunction = (typeof HARMONIC_FUNCTIONS)[number];
|
|
529
|
+
/**
|
|
530
|
+
* Whether a key's scale has a minor third and no major third (a minor key).
|
|
531
|
+
*
|
|
532
|
+
* @param key The key to test, as a key name, a key/scale, or a `Key`.
|
|
533
|
+
* @returns True if the key's scale is a minor one.
|
|
534
|
+
* @category Functional Harmony
|
|
535
|
+
*/
|
|
536
|
+
declare function isMinorKey(key: KeyLike): boolean;
|
|
537
|
+
/**
|
|
538
|
+
* The harmonic function of a chord in a key.
|
|
539
|
+
*
|
|
540
|
+
* The root's offset above the tonic gives the baseline mapping, which follows
|
|
541
|
+
* common-practice major-key function and is a useful approximation in minor and
|
|
542
|
+
* for borrowed chords. Chord quality then refines it where the sonority settles
|
|
543
|
+
* an ambiguity the root offset cannot:
|
|
544
|
+
*
|
|
545
|
+
* - A chord that *sounds* like a dominant — a major third with a minor seventh,
|
|
546
|
+
* or a diminished-family chord — and is neither diatonic to the key nor
|
|
547
|
+
* borrowed from its parallel mode has dominant function when its root
|
|
548
|
+
* resolves onto a degree that can be made a local tonic. This is what makes an
|
|
549
|
+
* applied dominant (`A7` in C, which tonicizes ii) and its tritone substitute
|
|
550
|
+
* (`Db7`) read as dominant rather than inheriting the function of the degree
|
|
551
|
+
* they happen to sit on. A bare major triad carries no tritone, so it only
|
|
552
|
+
* tonicizes by falling a fifth onto a degree other than the tonic: the Picardy
|
|
553
|
+
* third of a minor key and its borrowed major IV sound their own degrees.
|
|
554
|
+
* - The Neapolitan is subdominant.
|
|
555
|
+
* - An augmented sixth is subdominant. All three are altered predominants that
|
|
556
|
+
* resolve outward onto the dominant, so they take subdominant function even
|
|
557
|
+
* though the German sixth sounds a dominant seventh and would otherwise read
|
|
558
|
+
* as the tritone substitute it shares its pitch classes with.
|
|
559
|
+
* - A major triad on bVI or bVII of a major key is subdominant — the borrowed
|
|
560
|
+
* pop cadence chord, distinct from the bVII7 above, which has a seventh and
|
|
561
|
+
* is a dominant sonority.
|
|
562
|
+
*
|
|
563
|
+
* @param chord The chord, as a chord symbol, chord data, or a `Chord`.
|
|
564
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
565
|
+
* @returns The harmonic function.
|
|
566
|
+
* @example
|
|
567
|
+
* ```ts
|
|
568
|
+
* import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
|
|
569
|
+
* functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
|
|
570
|
+
* functionOf('Bb', 'C major'); // 'subdominant' — borrowed bVII
|
|
571
|
+
* ```
|
|
572
|
+
* @category Functional Harmony
|
|
573
|
+
*/
|
|
574
|
+
declare function functionOf(chord: ChordLike, key: KeyLike): HarmonicFunction;
|
|
575
|
+
/**
|
|
576
|
+
* The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
|
|
577
|
+
*
|
|
578
|
+
* @category Functional Harmony
|
|
579
|
+
*/
|
|
580
|
+
type ChordAnalysis = {
|
|
581
|
+
function: HarmonicFunction;
|
|
582
|
+
borrowed: boolean;
|
|
583
|
+
source: BorrowedSource;
|
|
584
|
+
roman: string;
|
|
585
|
+
/**
|
|
586
|
+
* Why the chord reads this way: the rule that settled its function, and where
|
|
587
|
+
* it was borrowed from when it was borrowed. Always present, in the phrasing
|
|
588
|
+
* {@link analyzeVoice} uses for a note.
|
|
589
|
+
*/
|
|
590
|
+
rationale: string;
|
|
591
|
+
/**
|
|
592
|
+
* The readings that were considered and rejected, empty unless the
|
|
593
|
+
* `alternatives` option of {@link AnalyzeChordOptions} asked for them.
|
|
594
|
+
*/
|
|
595
|
+
alternatives: RejectedCandidate[];
|
|
596
|
+
};
|
|
597
|
+
/**
|
|
598
|
+
* Options for {@link analyzeChord}: {@link ChordToRomanOptions} plus the switch
|
|
599
|
+
* for the rival readings.
|
|
600
|
+
*
|
|
601
|
+
* @category Functional Harmony
|
|
602
|
+
*/
|
|
603
|
+
type AnalyzeChordOptions = ChordToRomanOptions & {
|
|
604
|
+
/**
|
|
605
|
+
* Report the readings this analysis turned down: the function the chord's
|
|
606
|
+
* degree alone would have carried, the tonicizing reading a dominant sonority
|
|
607
|
+
* could have had, and the numerals the other rendering options would emit.
|
|
608
|
+
*
|
|
609
|
+
* Off by default. The rationale is built from facts the analysis already
|
|
610
|
+
* established, but a rival costs work nothing else needs — a second and third
|
|
611
|
+
* numeral rendering among them — and most callers read the conclusion only.
|
|
612
|
+
*
|
|
613
|
+
* @defaultValue false
|
|
614
|
+
*/
|
|
615
|
+
alternatives?: boolean;
|
|
616
|
+
};
|
|
617
|
+
/**
|
|
618
|
+
* Whether every pitch class of a chord belongs to the key's scale.
|
|
619
|
+
*
|
|
620
|
+
* The test is strict against the key's own mode mask: in a natural-minor key
|
|
621
|
+
* the harmonic-minor dominant (major V) is *not* diatonic, since the raised
|
|
622
|
+
* leading tone lies outside the mask. Borrowing predicates treat that case as
|
|
623
|
+
* an in-key alteration separately (see {@link isBorrowedChord}).
|
|
624
|
+
*
|
|
625
|
+
* @param chord The chord to test, as a chord symbol, chord data, or a `Chord`.
|
|
626
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
627
|
+
* @returns True if all chord pitch classes are scale tones.
|
|
628
|
+
* @category Functional Harmony
|
|
629
|
+
*/
|
|
630
|
+
declare function isDiatonic(chord: ChordLike, key: KeyLike): boolean;
|
|
631
|
+
/**
|
|
632
|
+
* Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.
|
|
633
|
+
*
|
|
634
|
+
* The function is quality-aware (see the predicates behind it), the source
|
|
635
|
+
* follows {@link borrowedSource}, and the numeral comes from
|
|
636
|
+
* {@link chordToRoman}. `borrowed` is true whenever a source is identified,
|
|
637
|
+
* which includes the Neapolitan: it belongs to neither parallel mode, and both
|
|
638
|
+
* this and {@link isBorrowedChord} count it as a borrowing all the same.
|
|
639
|
+
*
|
|
640
|
+
* The `rationale` says which of those rules settled the function, so a reader
|
|
641
|
+
* who disagrees can see what the reading rests on. `alternatives` is empty
|
|
642
|
+
* unless asked for, and then names the readings that were turned down.
|
|
643
|
+
*
|
|
644
|
+
* @param chord The chord to analyze, as a chord symbol, chord data, or a
|
|
645
|
+
* `Chord`.
|
|
646
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
647
|
+
* @param opts Options used when rendering the Roman numeral, plus
|
|
648
|
+
* `alternatives` to collect the rejected readings.
|
|
649
|
+
* @returns The chord analysis.
|
|
650
|
+
* @example
|
|
651
|
+
* ```ts
|
|
652
|
+
* import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
|
|
653
|
+
* analyzeChord(makeChord(7, 'dom7'), majorKey(0));
|
|
654
|
+
* // { function: 'dominant', borrowed: false, source: null, roman: 'V7', ... }
|
|
655
|
+
* analyzeChord(makeChord(9, 'dom7'), majorKey(0), { alternatives: true }).alternatives;
|
|
656
|
+
* // [{ label: 'tonic by scale degree', reason: '...' }, ...]
|
|
657
|
+
* ```
|
|
658
|
+
* @category Functional Harmony
|
|
659
|
+
*/
|
|
660
|
+
declare function analyzeChord(chord: ChordLike, key: KeyLike, opts?: AnalyzeChordOptions): ChordAnalysis;
|
|
661
|
+
/**
|
|
662
|
+
* The secondary dominant (V7) that tonicizes a scale degree.
|
|
663
|
+
*
|
|
664
|
+
* @param targetDegree 1-based scale degree to tonicize: 5 is the dominant, so
|
|
665
|
+
* `secondaryDominant(5, majorKey(0))` is the V of V.
|
|
666
|
+
* @param key The prevailing key, as a key name, a key/scale, or a `Key`.
|
|
667
|
+
* @returns A dominant-seventh chord a fifth above the target's root, spelled the
|
|
668
|
+
* way the key writes it (in Ab major the V of IV is Eb7, not D#7).
|
|
669
|
+
* @throws If `targetDegree` is not an integer naming a degree in `key`.
|
|
670
|
+
* @see {@link secondaryDominantOf} to tonicize a chord that has no degree in
|
|
671
|
+
* the key, or when no key is at hand.
|
|
672
|
+
* @category Functional Harmony
|
|
673
|
+
*/
|
|
674
|
+
declare function secondaryDominant(targetDegree: number, key: SpelledKeyLike): Chord;
|
|
675
|
+
/**
|
|
676
|
+
* The secondary dominant (V7) that tonicizes a chord.
|
|
677
|
+
*
|
|
678
|
+
* {@link secondaryDominant} names its target by scale degree, so it only
|
|
679
|
+
* reaches the degrees a key actually has. This takes the target chord itself
|
|
680
|
+
* and needs no key at all, which is what lets a borrowed or chromatic target —
|
|
681
|
+
* bVI of a major key, a Neapolitan, any chord a modulation left behind — have
|
|
682
|
+
* its dominant built without first inventing a degree for it.
|
|
683
|
+
*
|
|
684
|
+
* A `rootSpelling` hint on the target moves with the root, so a flat-named
|
|
685
|
+
* target yields a flat-named dominant (Eb gives Bb7, not A#7).
|
|
686
|
+
*
|
|
687
|
+
* @param target The chord to tonicize, as a chord symbol, chord data, or a
|
|
688
|
+
* `Chord`.
|
|
689
|
+
* @returns A dominant-seventh chord a perfect fifth above the target's root.
|
|
690
|
+
* @throws If the target's root pitch class is not a finite number.
|
|
691
|
+
* @example
|
|
692
|
+
* ```ts
|
|
693
|
+
* import { makeChord, secondaryDominantOf } from '@libraz/libcantus';
|
|
694
|
+
* secondaryDominantOf(makeChord(8, 'maj')).rootPc; // 3 — Eb7 tonicizes the
|
|
695
|
+
* // borrowed bVI of C major
|
|
696
|
+
* ```
|
|
697
|
+
* @category Functional Harmony
|
|
698
|
+
*/
|
|
699
|
+
declare function secondaryDominantOf(target: ChordLike): Chord;
|
|
700
|
+
|
|
701
|
+
/**
|
|
702
|
+
* Pivot chords: the common ground two keys share for a modulation.
|
|
703
|
+
*
|
|
704
|
+
* Roots are pitch classes measured against the key tonic, so the two readings
|
|
705
|
+
* of a pivot follow from the chord's degree in each key rather than requiring a
|
|
706
|
+
* spelled key signature.
|
|
707
|
+
*/
|
|
708
|
+
|
|
709
|
+
/**
|
|
710
|
+
* A chord that is diatonic to two keys at once, with its reading in each.
|
|
711
|
+
*
|
|
712
|
+
* @category Functional Harmony
|
|
713
|
+
*/
|
|
714
|
+
type PivotChord = {
|
|
715
|
+
/** The shared chord. */
|
|
716
|
+
chord: Chord;
|
|
717
|
+
/** Roman numeral in the key being left. */
|
|
718
|
+
romanFrom: string;
|
|
719
|
+
/** Roman numeral in the key being entered. */
|
|
720
|
+
romanTo: string;
|
|
721
|
+
};
|
|
722
|
+
/**
|
|
723
|
+
* List the chords a modulation from `from` to `to` can pivot on.
|
|
724
|
+
*
|
|
725
|
+
* A pivot chord belongs to both keys at once, so it can be heard as a degree of
|
|
726
|
+
* the key being left and reinterpreted as a degree of the key being entered —
|
|
727
|
+
* the seamless way into the new key. Candidates are the diatonic triads of
|
|
728
|
+
* `from`, degrees 1 through 7, kept when every one of their pitch classes is
|
|
729
|
+
* also a scale tone of `to`; the result is ordered by their degree in `from`.
|
|
730
|
+
*
|
|
731
|
+
* Only triads are candidates. The textbook pivot is a triad: a seventh narrows
|
|
732
|
+
* the shared ground by a whole tone for no analytical gain, and the chord that
|
|
733
|
+
* turns the modulation is heard as a triad whether or not a seventh is played
|
|
734
|
+
* over it.
|
|
735
|
+
*
|
|
736
|
+
* A key that is not heptatonic has no diatonic triads at all — stacking scale
|
|
737
|
+
* thirds only lands on a triad over seven degrees — so such a `from` key yields
|
|
738
|
+
* an empty list rather than an error. A `to` key is only tested for membership,
|
|
739
|
+
* so it may be any scale; its numerals then follow the {@link chordToRoman}
|
|
740
|
+
* fallback of naming roots against the parallel major.
|
|
741
|
+
*
|
|
742
|
+
* @param from The key being left, as a key name, a key/scale, or a `Key`; the
|
|
743
|
+
* shared chords are spelled the way it writes them.
|
|
744
|
+
* @param to The key being entered, in any of the same forms.
|
|
745
|
+
* @returns The shared triads, ascending by their degree in `from`.
|
|
746
|
+
* @example
|
|
747
|
+
* ```ts
|
|
748
|
+
* import { majorKey, pivotChords } from '@libraz/libcantus';
|
|
749
|
+
* pivotChords(majorKey(0), majorKey(7)).map((p) => `${p.romanFrom}=${p.romanTo}`);
|
|
750
|
+
* // ['I=IV', 'iii=vi', 'V=I', 'vi=ii'] — C major into G major
|
|
751
|
+
* ```
|
|
752
|
+
* @category Functional Harmony
|
|
753
|
+
*/
|
|
754
|
+
declare function pivotChords(from: SpelledKeyLike, to: SpelledKeyLike): PivotChord[];
|
|
755
|
+
|
|
756
|
+
/**
|
|
757
|
+
* The key as it changes over time.
|
|
758
|
+
*
|
|
759
|
+
* A piece that modulates has no single key, so a whole-piece answer is wrong
|
|
760
|
+
* for every bar after the modulation. This module answers instead with a run of
|
|
761
|
+
* regions, each carrying the key in force over one span, how it relates to the
|
|
762
|
+
* key before it, and — when chords are available — the chord the modulation
|
|
763
|
+
* turned on.
|
|
764
|
+
*/
|
|
765
|
+
|
|
766
|
+
/**
|
|
767
|
+
* A span of the piece over which one key is in force.
|
|
768
|
+
*
|
|
769
|
+
* @category Arrangement & Analysis
|
|
770
|
+
*/
|
|
771
|
+
type KeyRegion = {
|
|
772
|
+
/** First beat of the region. */
|
|
773
|
+
startBeat: number;
|
|
774
|
+
/** End of the region, exclusive. */
|
|
775
|
+
endBeat: number;
|
|
776
|
+
/**
|
|
777
|
+
* The key in force across the region, owned by it: every entry point hands
|
|
778
|
+
* back a key of the region's own, so writing to one changes neither the other
|
|
779
|
+
* regions of the same run nor what a later call reports.
|
|
780
|
+
*
|
|
781
|
+
* Whole, whichever way the region was built. A caller who named the key hands
|
|
782
|
+
* its spelling and scale form down, and a key the analysis found is spelled
|
|
783
|
+
* and formed the way {@link resolveKey} reads a bare scale — the reading every
|
|
784
|
+
* other layer would have made of it. There is no third state to guess at: a
|
|
785
|
+
* key/scale alone says nothing about how it is written, so a region carrying
|
|
786
|
+
* one would report whichever spelling those pitch classes read best from, and
|
|
787
|
+
* an Ab minor handed in would come back out a G# minor.
|
|
788
|
+
*/
|
|
789
|
+
key: ResolvedKey;
|
|
790
|
+
/**
|
|
791
|
+
* How well the region's music fits the key, in [0, 1]: the correlation
|
|
792
|
+
* between the span's pitch-class distribution and the key's profile, with
|
|
793
|
+
* negative correlations reported as 0.
|
|
794
|
+
*
|
|
795
|
+
* One statistic whichever entry point built the region, so a threshold or a
|
|
796
|
+
* comparison means the same thing across them. Where the region came from
|
|
797
|
+
* chords rather than notes, the distribution is each chord's tones weighted
|
|
798
|
+
* by how long the chord holds.
|
|
799
|
+
*/
|
|
800
|
+
confidence: number;
|
|
801
|
+
/**
|
|
802
|
+
* How this key relates to the previous region's — `'dominant'` for a move to
|
|
803
|
+
* the dominant, `'relative'` for a move to the relative minor, and so on.
|
|
804
|
+
* Absent on the first region, and absent when the two keys stand in none of
|
|
805
|
+
* the named relations.
|
|
806
|
+
*
|
|
807
|
+
* Never `'same'`: a region is the maximal span of one key, so consecutive
|
|
808
|
+
* regions never share one and a region carrying this field is a place the
|
|
809
|
+
* piece moved.
|
|
810
|
+
*/
|
|
811
|
+
modulation?: KeyRelation;
|
|
812
|
+
/**
|
|
813
|
+
* The chord the modulation turned on, when one was identified. Only the
|
|
814
|
+
* chord-aware entry points fill this in: a pivot is a chord that reads in
|
|
815
|
+
* both keys, so it cannot be named without knowing which chord sounded.
|
|
816
|
+
*/
|
|
817
|
+
pivot?: PivotChord;
|
|
818
|
+
};
|
|
819
|
+
/**
|
|
820
|
+
* Options shared by the key-region entry points.
|
|
821
|
+
*
|
|
822
|
+
* @category Arrangement & Analysis
|
|
823
|
+
*/
|
|
824
|
+
type KeyTimelineOptions = {
|
|
825
|
+
/**
|
|
826
|
+
* A single time signature held across the whole span, as sugar for a
|
|
827
|
+
* one-element `meters`; defaults to 4/4. Giving both is an input error.
|
|
828
|
+
*
|
|
829
|
+
* @defaultValue `4/4`
|
|
830
|
+
*/
|
|
831
|
+
ts?: MeterLike;
|
|
832
|
+
/**
|
|
833
|
+
* The meter as it changes over the span. Bar lines, downbeats and the metric
|
|
834
|
+
* accents the search discounts a modulation by all follow the signature in
|
|
835
|
+
* force at the beat in question, so a piece that changes meter is not read in
|
|
836
|
+
* the one it opened in.
|
|
837
|
+
*
|
|
838
|
+
* @defaultValue 4/4 throughout
|
|
839
|
+
*/
|
|
840
|
+
meters?: MeterLike;
|
|
841
|
+
/**
|
|
842
|
+
* Expected length of one key area in beats; defaults to four bars of the
|
|
843
|
+
* opening meter.
|
|
844
|
+
*
|
|
845
|
+
* This is a prior, not a window: the longer a key is expected to hold, the
|
|
846
|
+
* more evidence a modulation needs before the search will report one. Keys
|
|
847
|
+
* change far more slowly than chords do, which is why the default is measured
|
|
848
|
+
* in bars rather than beats.
|
|
849
|
+
*
|
|
850
|
+
* @defaultValue four bars of the opening meter
|
|
851
|
+
*/
|
|
852
|
+
expectedKeyBeats?: number;
|
|
853
|
+
/**
|
|
854
|
+
* Shortest key area the search may report, in beats; defaults to one bar of
|
|
855
|
+
* the opening meter. Values above `expectedKeyBeats` are clamped to it.
|
|
856
|
+
*
|
|
857
|
+
* @defaultValue one bar of the opening meter
|
|
858
|
+
*/
|
|
859
|
+
minKeyBeats?: number;
|
|
860
|
+
/**
|
|
861
|
+
* End of the analyzed span in beats; defaults to the end of the last note or
|
|
862
|
+
* chord segment.
|
|
863
|
+
*
|
|
864
|
+
* @defaultValue the end of the input
|
|
865
|
+
*/
|
|
866
|
+
totalBeats?: number;
|
|
867
|
+
/**
|
|
868
|
+
* Key profile the regions are scored against; defaults to `'krumhansl'`.
|
|
869
|
+
* Same meaning as the option of the same name on the key detectors.
|
|
870
|
+
*
|
|
871
|
+
* Every entry point reports `confidence` as the correlation between a
|
|
872
|
+
* region's pitch-class distribution and this profile, so the option is what
|
|
873
|
+
* that number is measured against. Which keys {@link detectModulations}
|
|
874
|
+
* reports is settled by how each chord reads in a key rather than by a
|
|
875
|
+
* pitch-class profile, so there the profile scores the answer without
|
|
876
|
+
* choosing it.
|
|
877
|
+
*
|
|
878
|
+
* @defaultValue `'krumhansl'`
|
|
879
|
+
*/
|
|
880
|
+
profile?: KeyProfileName | KeyProfilePair;
|
|
881
|
+
/**
|
|
882
|
+
* Upper bound on the work this call may do.
|
|
883
|
+
*
|
|
884
|
+
* @defaultValue {@link DEFAULT_GENERATION_BUDGET}
|
|
885
|
+
*/
|
|
886
|
+
budget?: number;
|
|
887
|
+
};
|
|
888
|
+
/**
|
|
889
|
+
* Infer where the key changes from raw notes.
|
|
890
|
+
*
|
|
891
|
+
* The span is examined in `minKeyBeats` slots. Each slot's pitch-class
|
|
892
|
+
* distribution is correlated against all 24 major and minor key profiles, and
|
|
893
|
+
* the run of keys that best explains the piece is chosen, paying a cost per
|
|
894
|
+
* modulation that rises with the distance travelled around the circle of
|
|
895
|
+
* fifths and falls on strong beats. Adjacent slots agreeing on a key become one
|
|
896
|
+
* region.
|
|
897
|
+
*
|
|
898
|
+
* The metric accents that discount a modulation follow the signature in force
|
|
899
|
+
* at the beat in question, so a piece that changes meter is read in the meter
|
|
900
|
+
* it is actually in. The first downbeat is beat 0, so a pickup is written at
|
|
901
|
+
* negative beats and its notes argue for the key like any others rather than
|
|
902
|
+
* falling outside the span.
|
|
903
|
+
*
|
|
904
|
+
* Pivot chords are not reported here: naming one requires knowing which chord
|
|
905
|
+
* sounded at the boundary, which raw notes do not say. Use
|
|
906
|
+
* {@link detectModulations} when a chord timeline is in hand.
|
|
907
|
+
*
|
|
908
|
+
* @param notes The notes to analyze (any number of tracks, flattened).
|
|
909
|
+
* @param opts Analysis options; see {@link KeyTimelineOptions}.
|
|
910
|
+
* @returns The key regions in time order; empty when nothing sounds.
|
|
911
|
+
* @example
|
|
912
|
+
* ```ts
|
|
913
|
+
* import { keyTimelineFromNotes } from '@libraz/libcantus';
|
|
914
|
+
* const notes = [
|
|
915
|
+
* { pitch: 60, startBeat: 0, durationBeat: 4 },
|
|
916
|
+
* { pitch: 64, startBeat: 4, durationBeat: 4 },
|
|
917
|
+
* ];
|
|
918
|
+
* const regions = keyTimelineFromNotes(notes);
|
|
919
|
+
* regions[0]?.key; // the key in force at the start
|
|
920
|
+
* ```
|
|
921
|
+
* @category Arrangement & Analysis
|
|
922
|
+
*/
|
|
923
|
+
declare function keyTimelineFromNotes(notes: readonly NoteEvent[], opts?: KeyTimelineOptions): KeyRegion[];
|
|
924
|
+
/**
|
|
925
|
+
* Infer where the key changes from a chord sequence, naming the pivot chords.
|
|
926
|
+
*
|
|
927
|
+
* Each chord segment is one slot of the same search {@link keyTimelineFromNotes}
|
|
928
|
+
* runs, scored by how well the chord belongs to each key rather than by a
|
|
929
|
+
* pitch-class profile — a dominant seventh argues for its key far more strongly
|
|
930
|
+
* than its three or four pitch classes alone would suggest. Where the key
|
|
931
|
+
* changes, the chord sounding into the boundary is reported as the pivot if it
|
|
932
|
+
* reads in both keys.
|
|
933
|
+
*
|
|
934
|
+
* The chords supply the slots, so `minKeyBeats` cannot size them as it does in
|
|
935
|
+
* the note path; a region shorter than it is folded into the neighbouring key
|
|
936
|
+
* that reads its chords best instead, which is the same guarantee — a shorter
|
|
937
|
+
* region is reported only where the analyzed span itself ends, or across a gap
|
|
938
|
+
* in the chords that no neighbour adjoins. `profile` scores each region's
|
|
939
|
+
* confidence, as it does in the note path, but takes no part in choosing which
|
|
940
|
+
* keys are reported: that is settled by how the chords read.
|
|
941
|
+
*
|
|
942
|
+
* A region's evidence is the run of segments it was grouped from, which is the
|
|
943
|
+
* same reading the search itself makes of them. Where the segments given
|
|
944
|
+
* overlap each other — a chart is a sequence, so a chord timeline's are not —
|
|
945
|
+
* a chord held past the segment after it argues for its own segment's key
|
|
946
|
+
* rather than for both.
|
|
947
|
+
*
|
|
948
|
+
* @param chords The chord segments to analyze, in time order; pass a chord
|
|
949
|
+
* timeline's `segments`.
|
|
950
|
+
* @param opts Analysis options; see {@link KeyTimelineOptions}.
|
|
951
|
+
* @returns The key regions in time order; empty when no chords were given.
|
|
952
|
+
* @example
|
|
953
|
+
* ```ts
|
|
954
|
+
* import { chordTimelineFromNotes, detectModulations } from '@libraz/libcantus';
|
|
955
|
+
* const notes = [
|
|
956
|
+
* { pitch: 60, startBeat: 0, durationBeat: 4 },
|
|
957
|
+
* { pitch: 64, startBeat: 0, durationBeat: 4 },
|
|
958
|
+
* { pitch: 67, startBeat: 0, durationBeat: 4 },
|
|
959
|
+
* ];
|
|
960
|
+
* const { timeline } = chordTimelineFromNotes(notes);
|
|
961
|
+
* const regions = detectModulations(timeline.segments);
|
|
962
|
+
* ```
|
|
963
|
+
* @category Arrangement & Analysis
|
|
964
|
+
*/
|
|
965
|
+
declare function detectModulations(chords: readonly ChordSegment[], opts?: KeyTimelineOptions): KeyRegion[];
|
|
966
|
+
/**
|
|
967
|
+
* The single key that holds for most of a run of regions.
|
|
968
|
+
*
|
|
969
|
+
* Callers that only want one key — a key signature to print, a scale to offer —
|
|
970
|
+
* need the one the piece spends the most time in, not the one it happens to
|
|
971
|
+
* start on.
|
|
972
|
+
*
|
|
973
|
+
* @param regions The regions to weigh, as returned by the key-region entry points.
|
|
974
|
+
* @returns The longest-held key, or null when there are no regions.
|
|
975
|
+
* @example
|
|
976
|
+
* ```ts
|
|
977
|
+
* import { keyTimelineFromNotes, prevailingKeyOf } from '@libraz/libcantus';
|
|
978
|
+
* const notes = [{ pitch: 60, startBeat: 0, durationBeat: 4 }];
|
|
979
|
+
* const key = prevailingKeyOf(keyTimelineFromNotes(notes));
|
|
980
|
+
* ```
|
|
981
|
+
* @category Arrangement & Analysis
|
|
982
|
+
*/
|
|
983
|
+
declare function prevailingKeyOf(regions: readonly KeyRegion[]): ResolvedKey | null;
|
|
984
|
+
|
|
985
|
+
/**
|
|
986
|
+
* A suspension figure, named by the interval above the bass and the interval it
|
|
987
|
+
* resolves to.
|
|
988
|
+
*
|
|
989
|
+
* A figure is reported only when the suspended note forms the interval the
|
|
990
|
+
* figure names. A dissonance that resolves by step from anywhere else — a
|
|
991
|
+
* retardation rising a semitone from the seventh to the octave, say — is left
|
|
992
|
+
* unfigured rather than named after an interval it does not form.
|
|
993
|
+
*
|
|
994
|
+
* @category Arrangement & Analysis
|
|
995
|
+
*/
|
|
996
|
+
type SuspensionFigure = 'sus4-3' | 'sus6-5' | 'sus7-6' | 'sus9-8' | 'sus2-3';
|
|
997
|
+
/**
|
|
998
|
+
* A theory annotation attached to a note.
|
|
999
|
+
*
|
|
1000
|
+
* @category Arrangement & Analysis
|
|
1001
|
+
*/
|
|
1002
|
+
type TheoryLabel = {
|
|
1003
|
+
kind: 'chordTone';
|
|
1004
|
+
role: ChordToneRole;
|
|
1005
|
+
} | {
|
|
1006
|
+
kind: 'tension';
|
|
1007
|
+
degree: 9 | 11 | 13;
|
|
1008
|
+
} | {
|
|
1009
|
+
kind: 'avoid';
|
|
1010
|
+
} | {
|
|
1011
|
+
kind: 'passing';
|
|
1012
|
+
} | {
|
|
1013
|
+
kind: 'neighbor';
|
|
1014
|
+
} | {
|
|
1015
|
+
kind: 'suspension';
|
|
1016
|
+
type: SuspensionFigure;
|
|
1017
|
+
resolveTo: number;
|
|
1018
|
+
}
|
|
1019
|
+
/**
|
|
1020
|
+
* A note leant on: reached by leap and given up by step the other way, with
|
|
1021
|
+
* `resolveTo` naming the pitch it gives way to. The word is the one
|
|
1022
|
+
* {@link MelodyToneRole} uses for the same figure, so a melody read through
|
|
1023
|
+
* this layer and through the harmonizer comes back under one vocabulary
|
|
1024
|
+
* rather than under two names for one note.
|
|
1025
|
+
*/
|
|
1026
|
+
| {
|
|
1027
|
+
kind: 'appoggiatura';
|
|
1028
|
+
resolveTo: number;
|
|
1029
|
+
} | {
|
|
1030
|
+
kind: 'anticipation';
|
|
1031
|
+
} | {
|
|
1032
|
+
kind: 'escape';
|
|
1033
|
+
} | {
|
|
1034
|
+
kind: 'needsResolution';
|
|
1035
|
+
resolveTo: number;
|
|
1036
|
+
} | {
|
|
1037
|
+
kind: 'leadingTone';
|
|
1038
|
+
resolveTo: number;
|
|
1039
|
+
};
|
|
1040
|
+
/**
|
|
1041
|
+
* A note with its theory labels and a short rationale.
|
|
1042
|
+
*
|
|
1043
|
+
* The labels describe the note against the chord sounding at its **onset**;
|
|
1044
|
+
* they are not re-derived for the later chords a long note sustains across.
|
|
1045
|
+
* `analyzeArrangement` does re-check every crossed chord change, and reports
|
|
1046
|
+
* what it finds as conflicts, so a note labelled a chord tone here can still
|
|
1047
|
+
* appear in `conflicts` at a later beat.
|
|
1048
|
+
*
|
|
1049
|
+
* The identity fields make an annotation mappable back to the caller's input:
|
|
1050
|
+
* `originalIndex` is the note's position in the array that was passed in, and
|
|
1051
|
+
* `trackIndex` is set by {@link analyzeArrangement}.
|
|
1052
|
+
*
|
|
1053
|
+
* @category Arrangement & Analysis
|
|
1054
|
+
*/
|
|
1055
|
+
type AnalyzedNote = {
|
|
1056
|
+
noteId: number;
|
|
1057
|
+
/** The note's index in the caller's own array, when the caller supplied one. */
|
|
1058
|
+
originalIndex?: number;
|
|
1059
|
+
/** The note's track, set by `analyzeArrangement`. */
|
|
1060
|
+
trackIndex?: number;
|
|
1061
|
+
pitch: number;
|
|
1062
|
+
startBeat: number;
|
|
1063
|
+
durationBeat: number;
|
|
1064
|
+
labels: TheoryLabel[];
|
|
1065
|
+
rationale?: string;
|
|
1066
|
+
};
|
|
1067
|
+
/**
|
|
1068
|
+
* A single note in a monophonic voice: a {@link NoteEvent} with a stable id and,
|
|
1069
|
+
* optionally, its index in the caller's original array.
|
|
1070
|
+
*
|
|
1071
|
+
* @category Arrangement & Analysis
|
|
1072
|
+
*/
|
|
1073
|
+
type VoiceNote = NoteEvent & {
|
|
1074
|
+
id?: number;
|
|
1075
|
+
originalIndex?: number;
|
|
1076
|
+
};
|
|
1077
|
+
/**
|
|
1078
|
+
* A voice note whose id has been assigned, as {@link toVoiceNotes} returns and
|
|
1079
|
+
* {@link analyzeArrangement} works in.
|
|
1080
|
+
*
|
|
1081
|
+
* @category Arrangement & Analysis
|
|
1082
|
+
*/
|
|
1083
|
+
type IdentifiedVoiceNote = VoiceNote & {
|
|
1084
|
+
id: number;
|
|
1085
|
+
};
|
|
1086
|
+
/**
|
|
1087
|
+
* A key that applies to the whole voice, or the key in force at a given beat.
|
|
1088
|
+
*
|
|
1089
|
+
* The callback form is what a piece that modulates needs: it is asked for the
|
|
1090
|
+
* key at a specific beat, the same way a chord is asked for with `chordAtBeat`.
|
|
1091
|
+
*
|
|
1092
|
+
* @example
|
|
1093
|
+
* ```ts
|
|
1094
|
+
* import { majorKey } from '@libraz/libcantus';
|
|
1095
|
+
* const wholePiece = majorKey(0); // C major throughout
|
|
1096
|
+
* const modulating = (beat: number) => (beat < 8 ? majorKey(5) : majorKey(0));
|
|
1097
|
+
* ```
|
|
1098
|
+
* @category Arrangement & Analysis
|
|
1099
|
+
*/
|
|
1100
|
+
type KeyContext = KeyLike | ((beat: number) => KeyScale);
|
|
1101
|
+
/**
|
|
1102
|
+
* Give plain note events the ids {@link analyzeVoice} reports back.
|
|
1103
|
+
*
|
|
1104
|
+
* The id is only an identity handle, so the array position serves; this exists
|
|
1105
|
+
* so the mapping is a named call rather than a `map` every caller writes.
|
|
1106
|
+
*
|
|
1107
|
+
* @param events The note events, in time order.
|
|
1108
|
+
* @returns The same notes as voice notes, each carrying its index as its id.
|
|
1109
|
+
* @category Arrangement & Analysis
|
|
1110
|
+
*/
|
|
1111
|
+
declare function toVoiceNotes(events: readonly NoteEvent[]): IdentifiedVoiceNote[];
|
|
1112
|
+
/**
|
|
1113
|
+
* Label every note of a voice with its theory roles.
|
|
1114
|
+
*
|
|
1115
|
+
* Each note is classified against the chord sounding at its beat. Chord tones
|
|
1116
|
+
* get a role label; non-chord tones are matched, in order, as suspensions
|
|
1117
|
+
* (prepared by an identical consonant pitch and resolving by step), passing
|
|
1118
|
+
* tones, neighbors, anticipations, appoggiaturas (approached by leap and
|
|
1119
|
+
* resolving by step the other way), and escape tones, then fall back to
|
|
1120
|
+
* tension, avoid, or an unresolved-dissonance label. The figures are named as
|
|
1121
|
+
* {@link classifyMelodyTones} names them, so a caller reading a melody through
|
|
1122
|
+
* both layers gets one vocabulary. The two answer different questions and
|
|
1123
|
+
* neither refines the other: that classifier weighs the metre, which this one is
|
|
1124
|
+
* not given, so it can call ornamental a note this one reads as a chord tone,
|
|
1125
|
+
* and the reverse. Leading-tone resolutions are noted
|
|
1126
|
+
* additionally, judged against the key in force at the beat the resolution
|
|
1127
|
+
* lands on, so a modulation is heard from its new tonic.
|
|
1128
|
+
*
|
|
1129
|
+
* The voice is expected to be monophonic (one note at a time). Notes sharing an
|
|
1130
|
+
* onset are treated as simultaneous cluster members, not melodic neighbors, so
|
|
1131
|
+
* they receive no melodic labels (suspension, passing, neighbor, anticipation,
|
|
1132
|
+
* escape) — only harmonic ones. Callers with truly polyphonic material should
|
|
1133
|
+
* split it into monophonic sub-voices first, as `analyzeArrangement` does. A
|
|
1134
|
+
* note of zero length sounds nothing: it gets no melodic labels and is no other
|
|
1135
|
+
* note's neighbour.
|
|
1136
|
+
*
|
|
1137
|
+
* @param voice The monophonic voice, in time order. A note without an `id` is
|
|
1138
|
+
* identified by its position, so plain note events can be passed straight in.
|
|
1139
|
+
* @param chordAtBeat Chord sounding at a given beat, or null.
|
|
1140
|
+
* @param key Key context for leading-tone detection: a single {@link KeyScale}
|
|
1141
|
+
* covering the whole voice, or a callback giving the key in force at a given
|
|
1142
|
+
* beat, for music that modulates.
|
|
1143
|
+
* @param otherVoicesAtBeat Other sounding voices at a given beat; defaults to
|
|
1144
|
+
* none, which is the whole story for a solo line: a suspension's dissonance
|
|
1145
|
+
* is then judged against the chord.
|
|
1146
|
+
* @returns One annotation per input note.
|
|
1147
|
+
* @example
|
|
1148
|
+
* ```ts
|
|
1149
|
+
* import { analyzeVoice, makeChord, majorKey } from '@libraz/libcantus';
|
|
1150
|
+
* const voice = [
|
|
1151
|
+
* { pitch: 60, startBeat: 0, durationBeat: 1 },
|
|
1152
|
+
* { pitch: 62, startBeat: 1, durationBeat: 1 },
|
|
1153
|
+
* { pitch: 64, startBeat: 2, durationBeat: 1 },
|
|
1154
|
+
* ];
|
|
1155
|
+
* const cMajor = makeChord(0, 'maj');
|
|
1156
|
+
* const labels = analyzeVoice(voice, () => cMajor, majorKey(0));
|
|
1157
|
+
* labels; // one AnalyzedNote per input note, in the same order
|
|
1158
|
+
* // A voice that modulates to C major at beat 2:
|
|
1159
|
+
* analyzeVoice(voice, () => cMajor, (beat) => (beat < 2 ? majorKey(5) : majorKey(0)));
|
|
1160
|
+
* ```
|
|
1161
|
+
* @category Arrangement & Analysis
|
|
1162
|
+
*/
|
|
1163
|
+
declare function analyzeVoice(voice: readonly VoiceNote[], chordAtBeat: (beat: number) => Chord | null, key: KeyContext, otherVoicesAtBeat?: (beat: number) => VoiceSnapshot[]): AnalyzedNote[];
|
|
1164
|
+
|
|
1165
|
+
/**
|
|
1166
|
+
* A beat-indexed sequence of chord segments.
|
|
1167
|
+
*
|
|
1168
|
+
* @category Arrangement & Analysis
|
|
1169
|
+
*/
|
|
1170
|
+
type ChordTimeline = {
|
|
1171
|
+
/**
|
|
1172
|
+
* The chord sounding at a beat, or null when no segment covers it. An
|
|
1173
|
+
* inferred timeline covers a rest shorter than its harmonic rhythm with the
|
|
1174
|
+
* chord around it; see {@link chordTimelineFromNotes}.
|
|
1175
|
+
*/
|
|
1176
|
+
at: (beat: number) => Chord | null;
|
|
1177
|
+
segments: ChordSegment[];
|
|
1178
|
+
};
|
|
1179
|
+
/**
|
|
1180
|
+
* Reject a value that is not a chord timeline.
|
|
1181
|
+
*
|
|
1182
|
+
* A timeline is the one argument a host is most likely to hold from somewhere
|
|
1183
|
+
* else — an in-memory project value, a previous run restored to a timeline, or
|
|
1184
|
+
* another library's output — and
|
|
1185
|
+
* it is read field by field deep inside an analysis. Checking it once at the
|
|
1186
|
+
* entrance names the argument that is wrong instead of reporting the library's
|
|
1187
|
+
* own `TypeError` from wherever the first `segments` lookup happened to be.
|
|
1188
|
+
*
|
|
1189
|
+
* The segments are checked too: every reader of a timeline compares beats, and
|
|
1190
|
+
* a segment whose bounds are missing compares as neither before nor after, so
|
|
1191
|
+
* it disappears from the analysis rather than being reported.
|
|
1192
|
+
*
|
|
1193
|
+
* @param timeline The timeline as the caller passed it.
|
|
1194
|
+
* @param name What the argument is called in an error message.
|
|
1195
|
+
* @returns The same timeline.
|
|
1196
|
+
* @throws If the value is not a timeline of chord segments.
|
|
1197
|
+
* @example
|
|
1198
|
+
* ```ts
|
|
1199
|
+
* import { assertChordTimeline, chordTimelineFromChords } from '@libraz/libcantus';
|
|
1200
|
+
* assertChordTimeline(chordTimelineFromChords([], 4)); // the timeline, unchanged
|
|
1201
|
+
* ```
|
|
1202
|
+
* @category Arrangement & Analysis
|
|
1203
|
+
*/
|
|
1204
|
+
declare function assertChordTimeline(timeline: ChordTimeline, name?: string): ChordTimeline;
|
|
1205
|
+
/**
|
|
1206
|
+
* Build a chord timeline from placed chords.
|
|
1207
|
+
*
|
|
1208
|
+
* Each chord spans from its `startBeat` to the next chord's `startBeat`; the last
|
|
1209
|
+
* chord runs to `totalBeats`. Segments with no positive length (from duplicate
|
|
1210
|
+
* onsets or a last chord at or past `totalBeats`) are dropped. `at(beat)` returns
|
|
1211
|
+
* the covering segment's chord, or null when the beat lies outside every segment.
|
|
1212
|
+
*
|
|
1213
|
+
* @param chords Placed chords in time order.
|
|
1214
|
+
* @param totalBeats End of the timeline in beats.
|
|
1215
|
+
* @returns A queryable chord timeline.
|
|
1216
|
+
* @category Arrangement & Analysis
|
|
1217
|
+
*/
|
|
1218
|
+
declare function chordTimelineFromChords(chords: readonly ChordSpan[], totalBeats: number): ChordTimeline;
|
|
1219
|
+
/**
|
|
1220
|
+
* How {@link chordTimelineFromNotes} decides where one chord ends and the next
|
|
1221
|
+
* begins.
|
|
1222
|
+
*
|
|
1223
|
+
* `'dynamic'` searches for the boundaries the notes actually imply, so a bar
|
|
1224
|
+
* holding two chords yields two segments and a bar holding one yields one.
|
|
1225
|
+
* `'grid'` cuts a segment every `harmonicRhythm` beats regardless of what
|
|
1226
|
+
* sounds, which is only right when the harmonic rhythm is known to be fixed.
|
|
1227
|
+
*
|
|
1228
|
+
* @category Arrangement & Analysis
|
|
1229
|
+
*/
|
|
1230
|
+
type ChordSegmentation = 'dynamic' | 'grid';
|
|
1231
|
+
/**
|
|
1232
|
+
* Options controlling {@link chordTimelineFromNotes}.
|
|
1233
|
+
*
|
|
1234
|
+
* @category Arrangement & Analysis
|
|
1235
|
+
*/
|
|
1236
|
+
type ChordTimelineOptions = {
|
|
1237
|
+
/**
|
|
1238
|
+
* Key context held across the whole span. Omit it to have the key searched
|
|
1239
|
+
* for over time with {@link keyTimelineFromNotes}, which is what lets a piece
|
|
1240
|
+
* that modulates be analysed against the key actually in force.
|
|
1241
|
+
*
|
|
1242
|
+
* Taken in whatever form the caller holds a key, and kept whole: the region
|
|
1243
|
+
* built from it carries the spelling and the scale form it was named with, so
|
|
1244
|
+
* an Ab minor stated here is an Ab minor in the result.
|
|
1245
|
+
*/
|
|
1246
|
+
key?: KeyLike;
|
|
1247
|
+
/**
|
|
1248
|
+
* A single time signature held across the whole span, as sugar for a
|
|
1249
|
+
* one-element `meters`; defaults to 4/4. Giving both is an input error.
|
|
1250
|
+
*
|
|
1251
|
+
* @defaultValue `4/4`
|
|
1252
|
+
*/
|
|
1253
|
+
ts?: MeterLike;
|
|
1254
|
+
/**
|
|
1255
|
+
* The meter as it changes over the span. Bar lines, downbeats and metric
|
|
1256
|
+
* weight all follow the signature in force at the beat in question, so a
|
|
1257
|
+
* piece that changes meter is not read in the one it opened in.
|
|
1258
|
+
*
|
|
1259
|
+
* @defaultValue 4/4 throughout
|
|
1260
|
+
*/
|
|
1261
|
+
meters?: MeterLike;
|
|
1262
|
+
/**
|
|
1263
|
+
* Length of the pickup in beats, when the piece starts with one.
|
|
1264
|
+
*
|
|
1265
|
+
* The first downbeat is beat 0 whatever precedes it, so an upbeat is written
|
|
1266
|
+
* at negative beats — a one-beat pickup in 4/4 sounds at beat -1. Declaring
|
|
1267
|
+
* its length rejects a note that starts before the pickup does; leave it
|
|
1268
|
+
* unset to accept any onset within ±`Number.MAX_SAFE_INTEGER` (2^53 - 1).
|
|
1269
|
+
*
|
|
1270
|
+
* @defaultValue no declared pickup
|
|
1271
|
+
*/
|
|
1272
|
+
pickupBeats?: number;
|
|
1273
|
+
/**
|
|
1274
|
+
* Where chord boundaries may fall; defaults to `'dynamic'`. Any other value
|
|
1275
|
+
* is an input error.
|
|
1276
|
+
*
|
|
1277
|
+
* @defaultValue `'dynamic'`
|
|
1278
|
+
*/
|
|
1279
|
+
segmentation?: ChordSegmentation;
|
|
1280
|
+
/**
|
|
1281
|
+
* Expected chord length in beats; defaults to the length of the opening bar.
|
|
1282
|
+
*
|
|
1283
|
+
* Under `'grid'` segmentation this is the exact window length. Under
|
|
1284
|
+
* `'dynamic'` it is a prior: the longer a chord is expected to last, the more
|
|
1285
|
+
* evidence a change needs before the search will place one.
|
|
1286
|
+
*
|
|
1287
|
+
* @defaultValue the length of the opening bar
|
|
1288
|
+
*/
|
|
1289
|
+
harmonicRhythm?: number;
|
|
1290
|
+
/**
|
|
1291
|
+
* Resolution the `'dynamic'` search looks for changes at, in beats; defaults
|
|
1292
|
+
* to one main pulse of the meter — a quarter in 4/4, a dotted quarter in 6/8.
|
|
1293
|
+
* Lower it to catch changes on off-beats, at the cost of proportionally more
|
|
1294
|
+
* work. Values above `harmonicRhythm` are clamped to it, and the option is
|
|
1295
|
+
* ignored under `'grid'` segmentation.
|
|
1296
|
+
*
|
|
1297
|
+
* The search reads it as a resolution rather than as an exact slot length: it
|
|
1298
|
+
* rounds down to a whole division of the meter's pulse, so `0.6` in 4/4 is
|
|
1299
|
+
* read in half-beats. That keeps every pulse of the meter, and the bar lines
|
|
1300
|
+
* with them, on the grid whatever resolution is asked for, and with them every
|
|
1301
|
+
* change a coarser setting found. A resolution coarser than one pulse is
|
|
1302
|
+
* therefore read as one pulse rather than stepping over the beats a change is
|
|
1303
|
+
* heard on.
|
|
1304
|
+
*
|
|
1305
|
+
* @defaultValue one main pulse of the meter
|
|
1306
|
+
*/
|
|
1307
|
+
minChordBeats?: number;
|
|
1308
|
+
/**
|
|
1309
|
+
* End of the analyzed span in beats; defaults to the end of the last note.
|
|
1310
|
+
*
|
|
1311
|
+
* @defaultValue the end of the last note
|
|
1312
|
+
*/
|
|
1313
|
+
totalBeats?: number;
|
|
1314
|
+
/**
|
|
1315
|
+
* Upper bound on the work this call may do — note counts, windows, and
|
|
1316
|
+
* candidate counts are each checked against it before anything is allocated.
|
|
1317
|
+
*
|
|
1318
|
+
* Raise it to analyse a piece larger than the default allows; the default is
|
|
1319
|
+
* {@link DEFAULT_GENERATION_BUDGET}, chosen so a runaway input fails fast
|
|
1320
|
+
* rather than blocking the thread.
|
|
1321
|
+
*
|
|
1322
|
+
* @defaultValue {@link DEFAULT_GENERATION_BUDGET}
|
|
1323
|
+
*/
|
|
1324
|
+
budget?: number;
|
|
1325
|
+
};
|
|
1326
|
+
/**
|
|
1327
|
+
* The result of {@link chordTimelineFromNotes}.
|
|
1328
|
+
*
|
|
1329
|
+
* @category Arrangement & Analysis
|
|
1330
|
+
*/
|
|
1331
|
+
type ChordTimelineResult = {
|
|
1332
|
+
/** The inferred timeline, with adjacent identical chords merged. */
|
|
1333
|
+
timeline: ChordTimeline;
|
|
1334
|
+
/**
|
|
1335
|
+
* The key regions the analysis ran against, in time order. A piece that does
|
|
1336
|
+
* not modulate yields one region covering the whole span; a given `key`
|
|
1337
|
+
* yields exactly one region too, since the caller has already answered the
|
|
1338
|
+
* question. Either way the first region starts where the analysis does, which
|
|
1339
|
+
* is before beat 0 when the piece opens with a pickup. Pivot chords are filled
|
|
1340
|
+
* in where the chords support one.
|
|
1341
|
+
*/
|
|
1342
|
+
keys: KeyRegion[];
|
|
1343
|
+
/**
|
|
1344
|
+
* The key held longest across {@link ChordTimelineResult.keys} — the one to
|
|
1345
|
+
* print on a key signature or hand to a generator that takes a single key.
|
|
1346
|
+
*/
|
|
1347
|
+
prevailingKey: ResolvedKey;
|
|
1348
|
+
/** One confidence value in [0, 1] per segment, in segment order. */
|
|
1349
|
+
segmentConfidence: number[];
|
|
1350
|
+
};
|
|
1351
|
+
/**
|
|
1352
|
+
* Infer a chord timeline from raw multi-track notes.
|
|
1353
|
+
*
|
|
1354
|
+
* Chord boundaries are searched for rather than assumed: the span is examined
|
|
1355
|
+
* in slots of one main pulse, subdivided as finely as `minChordBeats` asks for,
|
|
1356
|
+
* and the change points that best explain the notes
|
|
1357
|
+
* are chosen, trading each slot's harmonic fit against a cost per chord change
|
|
1358
|
+
* that a strong beat discounts. A bar holding two chords therefore yields two
|
|
1359
|
+
* segments and a bar holding one yields one, without the caller having to know
|
|
1360
|
+
* the harmonic rhythm in advance. Pass `segmentation: 'grid'` to cut a segment
|
|
1361
|
+
* every `harmonicRhythm` beats instead.
|
|
1362
|
+
*
|
|
1363
|
+
* Each settled segment's chord is inferred from a pitch-class weight histogram
|
|
1364
|
+
* of the notes overlapping it (weight = overlap duration x velocity x
|
|
1365
|
+
* metric-accent bonus for onsets in the segment). Adjacent segments carrying
|
|
1366
|
+
* the identical chord are merged. Under `'dynamic'` segmentation a silence at
|
|
1367
|
+
* least `harmonicRhythm` long produces no segment, so `at(beat)` returns null
|
|
1368
|
+
* there, while a shorter rest is absorbed into the chord around it — a C triad
|
|
1369
|
+
* for two beats, two beats of rest and a G triad read C over beats 0-4. Under `'grid'` any
|
|
1370
|
+
* window with nothing sounding produces no segment. A window whose notes give
|
|
1371
|
+
* fewer than two tones of any chord produces none either: a lone pitch class
|
|
1372
|
+
* names no chord. Each segment carries a confidence in [0, 1]
|
|
1373
|
+
* — the fraction of its weight explained by chord tones, reduced when the match
|
|
1374
|
+
* is inexact, and duration-weighted across anything merged into it.
|
|
1375
|
+
*
|
|
1376
|
+
* Notes with a zero or negative duration never sound, so they are dropped at
|
|
1377
|
+
* ingest: they contribute to neither the key inference, the span, nor any
|
|
1378
|
+
* window's histogram.
|
|
1379
|
+
*
|
|
1380
|
+
* Bar lines, downbeats and the metric accents the boundary search discounts by
|
|
1381
|
+
* all follow the signature in force at the beat in question, so a piece that
|
|
1382
|
+
* changes meter is read in the meter it is actually in. The first downbeat is
|
|
1383
|
+
* beat 0, so a pickup is written at negative beats and the search still finds
|
|
1384
|
+
* the bar lines where the score has them.
|
|
1385
|
+
*
|
|
1386
|
+
* @param notes The notes to analyze (any number of tracks, flattened).
|
|
1387
|
+
* @param opts Analysis options; see {@link ChordTimelineOptions}.
|
|
1388
|
+
* @returns The inferred timeline, the key regions it ran against, the key that
|
|
1389
|
+
* prevails across them, and per-segment confidences.
|
|
1390
|
+
* @throws If `harmonicRhythm` is not positive, or `segmentation` names neither
|
|
1391
|
+
* mode.
|
|
1392
|
+
* @example
|
|
1393
|
+
* ```ts
|
|
1394
|
+
* import { chordTimelineFromNotes } from '@libraz/libcantus';
|
|
1395
|
+
* const notes = [
|
|
1396
|
+
* { pitch: 60, startBeat: 0, durationBeat: 2 }, // C
|
|
1397
|
+
* { pitch: 64, startBeat: 0, durationBeat: 2 }, // E
|
|
1398
|
+
* { pitch: 67, startBeat: 0, durationBeat: 2 }, // G
|
|
1399
|
+
* ];
|
|
1400
|
+
* const { timeline, prevailingKey } = chordTimelineFromNotes(notes);
|
|
1401
|
+
* timeline.at(0); // the chord inferred over beat 0, or null
|
|
1402
|
+
* prevailingKey; // the key held longest across the piece
|
|
1403
|
+
* ```
|
|
1404
|
+
* @category Arrangement & Analysis
|
|
1405
|
+
*/
|
|
1406
|
+
declare function chordTimelineFromNotes(notes: readonly NoteEvent[], opts?: ChordTimelineOptions): ChordTimelineResult;
|
|
1407
|
+
/**
|
|
1408
|
+
* A cadence found between two consecutive timeline segments.
|
|
1409
|
+
*
|
|
1410
|
+
* @category Arrangement & Analysis
|
|
1411
|
+
*/
|
|
1412
|
+
type CadenceHit = {
|
|
1413
|
+
/** The beat where the cadence arrives (the second chord's onset). */
|
|
1414
|
+
atBeat: number;
|
|
1415
|
+
/**
|
|
1416
|
+
* The cadence formed by the pair. Its `type` is never null: a pair forming no
|
|
1417
|
+
* cadence is not a hit. A timeline names no voicing, so `strength` is null for
|
|
1418
|
+
* an authentic cadence whose chords are both in root position.
|
|
1419
|
+
*/
|
|
1420
|
+
cadence: CadenceResult;
|
|
1421
|
+
from: Chord;
|
|
1422
|
+
to: Chord;
|
|
1423
|
+
};
|
|
1424
|
+
/**
|
|
1425
|
+
* Find cadences between consecutive segments of a chord timeline.
|
|
1426
|
+
*
|
|
1427
|
+
* Each temporally adjacent segment pair is classified with
|
|
1428
|
+
* {@link detectCadence}; pairs forming no cadence are skipped. Segments
|
|
1429
|
+
* separated by a gap (a rest in the timeline) are not a chord-to-chord
|
|
1430
|
+
* progression, so they are never paired.
|
|
1431
|
+
*
|
|
1432
|
+
* The segment before the pair is passed as the approach, which is what tells a
|
|
1433
|
+
* cadential six-four from an inverted tonic: `I I64 V I` is one cadence
|
|
1434
|
+
* arriving on the final tonic, described from the six-four the dominant was
|
|
1435
|
+
* already sounding under, rather than a half cadence onto the dominant
|
|
1436
|
+
* followed by an authentic one. A passing six-four — one whose dominant is not
|
|
1437
|
+
* what follows it — is unaffected, and so is a pair whose predecessor is
|
|
1438
|
+
* separated from it by a rest.
|
|
1439
|
+
*
|
|
1440
|
+
* @param timeline The chord timeline to scan.
|
|
1441
|
+
* @param key The prevailing key, or the key in force at a given beat.
|
|
1442
|
+
* @returns The cadences found, in time order.
|
|
1443
|
+
* @example
|
|
1444
|
+
* ```ts
|
|
1445
|
+
* import { chordTimelineFromNotes, detectCadences } from '@libraz/libcantus';
|
|
1446
|
+
* const triad = (pitches: number[], startBeat: number) =>
|
|
1447
|
+
* pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
|
|
1448
|
+
* const notes = [...triad([55, 59, 62], 0), ...triad([48, 52, 55], 4)]; // G, then C
|
|
1449
|
+
* const { timeline, prevailingKey } = chordTimelineFromNotes(notes);
|
|
1450
|
+
* const cadences = detectCadences(timeline, prevailingKey);
|
|
1451
|
+
* ```
|
|
1452
|
+
* @category Arrangement & Analysis
|
|
1453
|
+
*/
|
|
1454
|
+
declare function detectCadences(timeline: ChordTimeline, key: KeyContext): CadenceHit[];
|
|
1455
|
+
|
|
1456
|
+
/**
|
|
1457
|
+
* Sections: the largest unit this library reads, recovered from repetition.
|
|
1458
|
+
*
|
|
1459
|
+
* A section is found, not named. What the analysis can see is that a span of
|
|
1460
|
+
* music is a restatement of an earlier one, so the spans are labelled by order
|
|
1461
|
+
* of first appearance — A, B, C — and nothing more is claimed. Calling a
|
|
1462
|
+
* repeated span a chorus would be a guess dressed as a finding: repetition
|
|
1463
|
+
* alone cannot tell a chorus from a second verse, and the label a listener
|
|
1464
|
+
* would give depends on lyrics, arrangement and loudness that the notes do not
|
|
1465
|
+
* carry.
|
|
1466
|
+
*/
|
|
1467
|
+
|
|
1468
|
+
/**
|
|
1469
|
+
* A span of music labelled by which earlier span it restates.
|
|
1470
|
+
*
|
|
1471
|
+
* @category Arrangement & Analysis
|
|
1472
|
+
*/
|
|
1473
|
+
type FormSection = {
|
|
1474
|
+
/**
|
|
1475
|
+
* The section's letter, assigned in order of first appearance: the opening
|
|
1476
|
+
* material is A, the first material unlike it is B, and a later restatement
|
|
1477
|
+
* of A is A again. Past Z the letters double (AA, AB), the way spreadsheet
|
|
1478
|
+
* columns do. No functional name — verse, chorus, bridge — is ever inferred.
|
|
1479
|
+
*/
|
|
1480
|
+
label: string;
|
|
1481
|
+
/** First beat of the section; negative when it opens with a pickup. */
|
|
1482
|
+
startBeat: number;
|
|
1483
|
+
/** End of the section, exclusive. */
|
|
1484
|
+
endBeat: number;
|
|
1485
|
+
/** The section's length in bars. */
|
|
1486
|
+
bars: number;
|
|
1487
|
+
/**
|
|
1488
|
+
* Index, in the returned array, of the first section carrying this label; the
|
|
1489
|
+
* section's own index when it is that first appearance.
|
|
1490
|
+
*/
|
|
1491
|
+
firstOccurrence: number;
|
|
1492
|
+
/**
|
|
1493
|
+
* How alike this section and its first occurrence are, in [0, 1]; 1 on the
|
|
1494
|
+
* first occurrence itself. The mean over the units the section was merged
|
|
1495
|
+
* from, each scored against the unit it matched.
|
|
1496
|
+
*/
|
|
1497
|
+
similarity: number;
|
|
1498
|
+
/** How the section came to carry its label. */
|
|
1499
|
+
rationale: string;
|
|
1500
|
+
};
|
|
1501
|
+
/**
|
|
1502
|
+
* Options for {@link sectionsFromNotes}.
|
|
1503
|
+
*
|
|
1504
|
+
* @category Arrangement & Analysis
|
|
1505
|
+
*/
|
|
1506
|
+
type FormSectionOptions = {
|
|
1507
|
+
/**
|
|
1508
|
+
* A single time signature held across the whole span, as sugar for a
|
|
1509
|
+
* one-element `meters`; defaults to 4/4. Giving both is an input error.
|
|
1510
|
+
*
|
|
1511
|
+
* @defaultValue `4/4`
|
|
1512
|
+
*/
|
|
1513
|
+
ts?: MeterLike;
|
|
1514
|
+
/**
|
|
1515
|
+
* The meter as it changes over the span, so a piece that changes metre is cut
|
|
1516
|
+
* at its own bar lines.
|
|
1517
|
+
*
|
|
1518
|
+
* @defaultValue 4/4 throughout
|
|
1519
|
+
*/
|
|
1520
|
+
meters?: MeterLike;
|
|
1521
|
+
/**
|
|
1522
|
+
* Length of the unit spans are compared in, in bars; defaults to one hyperbar.
|
|
1523
|
+
*
|
|
1524
|
+
* Sections are found by comparing equal units and merging the neighbours that
|
|
1525
|
+
* match, so this is the resolution of the answer rather than the length of a
|
|
1526
|
+
* section: a section is any whole number of units long.
|
|
1527
|
+
*
|
|
1528
|
+
* @defaultValue the inferred hyperbar, in bars
|
|
1529
|
+
*/
|
|
1530
|
+
unitBars?: number;
|
|
1531
|
+
/**
|
|
1532
|
+
* How alike two units must be before the later one is called a restatement of
|
|
1533
|
+
* the earlier, in [0, 1].
|
|
1534
|
+
*
|
|
1535
|
+
* @defaultValue `0.8`
|
|
1536
|
+
*/
|
|
1537
|
+
threshold?: number;
|
|
1538
|
+
/**
|
|
1539
|
+
* End of the analysed span in beats; defaults to the end of the last note.
|
|
1540
|
+
*
|
|
1541
|
+
* @defaultValue the end of the last note
|
|
1542
|
+
*/
|
|
1543
|
+
totalBeats?: number;
|
|
1544
|
+
/**
|
|
1545
|
+
* Upper bound on the work this call may do.
|
|
1546
|
+
*
|
|
1547
|
+
* @defaultValue {@link DEFAULT_GENERATION_BUDGET}
|
|
1548
|
+
*/
|
|
1549
|
+
budget?: number;
|
|
1550
|
+
};
|
|
1551
|
+
/**
|
|
1552
|
+
* Recover a piece's sections from what it repeats.
|
|
1553
|
+
*
|
|
1554
|
+
* The span is cut into equal units of `unitBars` bars, each unit is compared
|
|
1555
|
+
* with every unit before it, and a unit alike enough to an earlier one takes
|
|
1556
|
+
* that unit's label. Neighbouring units carrying the same label are then merged,
|
|
1557
|
+
* so an eight-bar section built of two like four-bar units is reported as one
|
|
1558
|
+
* section rather than two.
|
|
1559
|
+
*
|
|
1560
|
+
* Likeness is measured on the melodic line and on the harmonic content
|
|
1561
|
+
* together — the same tune under different harmony is a variation, not a
|
|
1562
|
+
* restatement — and the labels are letters in order of first appearance.
|
|
1563
|
+
* Nothing beyond "this is a restatement of that" is asserted: see
|
|
1564
|
+
* {@link FormSection.label}.
|
|
1565
|
+
*
|
|
1566
|
+
* A pickup belongs to the section it leads into, so material before the first
|
|
1567
|
+
* bar is folded into the opening unit rather than made a section of its own.
|
|
1568
|
+
*
|
|
1569
|
+
* @param notes The piece's notes, in any order. Notes that never sound are
|
|
1570
|
+
* dropped.
|
|
1571
|
+
* @param opts Analysis options; see {@link FormSectionOptions}.
|
|
1572
|
+
* @returns The sections, in time order.
|
|
1573
|
+
* @example
|
|
1574
|
+
* ```ts
|
|
1575
|
+
* import { sectionsFromNotes } from '@libraz/libcantus';
|
|
1576
|
+
* const bar = (pitch: number, at: number) => ({ pitch, startBeat: at, durationBeat: 4 });
|
|
1577
|
+
* const notes = [bar(60, 0), bar(64, 4), bar(67, 8), bar(60, 12)];
|
|
1578
|
+
* sectionsFromNotes(notes, { unitBars: 2 }).map((section) => section.label);
|
|
1579
|
+
* ```
|
|
1580
|
+
* @category Arrangement & Analysis
|
|
1581
|
+
*/
|
|
1582
|
+
declare function sectionsFromNotes(notes: readonly NoteEvent[], opts?: FormSectionOptions): FormSection[];
|
|
1583
|
+
|
|
1584
|
+
/**
|
|
1585
|
+
* The recurring cells a melody is built from.
|
|
1586
|
+
*
|
|
1587
|
+
* A motif is the interval contour plus the rhythmic profile, so every statement
|
|
1588
|
+
* of it carries the same identity however far it has been transposed or however
|
|
1589
|
+
* wide its note values are written. What this module does is find them: every
|
|
1590
|
+
* window of the melody is reduced to that identity, windows that agree are
|
|
1591
|
+
* grouped, and a group stated often enough is a motif.
|
|
1592
|
+
*/
|
|
1593
|
+
|
|
1594
|
+
/**
|
|
1595
|
+
* One statement of a motif, addressed in the melody it was found in.
|
|
1596
|
+
*
|
|
1597
|
+
* The notes themselves are not repeated here: a statement is the motif's notes
|
|
1598
|
+
* moved by `transpose` and stretched by `timeRatio`, and `noteIndex` addresses
|
|
1599
|
+
* the original array for a caller that wants them exactly.
|
|
1600
|
+
*
|
|
1601
|
+
* @category Arrangement & Analysis
|
|
1602
|
+
*/
|
|
1603
|
+
type MotifOccurrence = {
|
|
1604
|
+
/**
|
|
1605
|
+
* Index of the statement's first note among the sounding notes of the melody,
|
|
1606
|
+
* in time order. Notes that never sound are dropped before the search, so this
|
|
1607
|
+
* is not an index into the caller's array unless the caller's array has none.
|
|
1608
|
+
*/
|
|
1609
|
+
noteIndex: number;
|
|
1610
|
+
/** Onset of the statement's first note. */
|
|
1611
|
+
startBeat: number;
|
|
1612
|
+
/** End of the statement's last note, exclusive. */
|
|
1613
|
+
endBeat: number;
|
|
1614
|
+
/** Semitones this statement stands above the motif's first statement. */
|
|
1615
|
+
transpose: number;
|
|
1616
|
+
/**
|
|
1617
|
+
* How much this statement is stretched against the motif's first: 2 for a
|
|
1618
|
+
* statement in doubled note values, 0.5 for one in halved values, 1 for one in
|
|
1619
|
+
* the same values.
|
|
1620
|
+
*/
|
|
1621
|
+
timeRatio: number;
|
|
1622
|
+
};
|
|
1623
|
+
/**
|
|
1624
|
+
* A recurring melodic cell.
|
|
1625
|
+
*
|
|
1626
|
+
* Identity is the interval sequence plus the rhythmic profile, so every
|
|
1627
|
+
* statement of the motif carries the same `intervals` and `rhythm` however far
|
|
1628
|
+
* it has been transposed or however wide its note values are written. `notes`
|
|
1629
|
+
* holds one statement — the first — exactly as it sounds.
|
|
1630
|
+
*
|
|
1631
|
+
* @category Arrangement & Analysis
|
|
1632
|
+
*/
|
|
1633
|
+
type MotifData = {
|
|
1634
|
+
/** The first statement, exactly as it sounds in the melody. */
|
|
1635
|
+
notes: NoteEvent[];
|
|
1636
|
+
/**
|
|
1637
|
+
* Semitones between consecutive notes. This is the transposition-invariant
|
|
1638
|
+
* identity of the cell: two statements a fifth apart share it.
|
|
1639
|
+
*/
|
|
1640
|
+
intervals: number[];
|
|
1641
|
+
/**
|
|
1642
|
+
* Onset-to-onset gaps as multiples of the first gap, so an even cell reads
|
|
1643
|
+
* `[1, 1, 1]` whatever the tempo or note values it is written in.
|
|
1644
|
+
*/
|
|
1645
|
+
rhythm: number[];
|
|
1646
|
+
/** Every statement found, in time order; the first is `notes`. */
|
|
1647
|
+
occurrences: MotifOccurrence[];
|
|
1648
|
+
/** Why this counts as a motif. */
|
|
1649
|
+
rationale: string;
|
|
1650
|
+
};
|
|
1651
|
+
/**
|
|
1652
|
+
* Options controlling {@link extractMotifs}.
|
|
1653
|
+
*
|
|
1654
|
+
* @category Arrangement & Analysis
|
|
1655
|
+
*/
|
|
1656
|
+
type ExtractMotifsOptions = {
|
|
1657
|
+
/**
|
|
1658
|
+
* Shortest cell to report, in notes.
|
|
1659
|
+
*
|
|
1660
|
+
* @defaultValue 3
|
|
1661
|
+
*/
|
|
1662
|
+
minNotes?: number;
|
|
1663
|
+
/**
|
|
1664
|
+
* Longest cell to report, in notes.
|
|
1665
|
+
*
|
|
1666
|
+
* @defaultValue 8
|
|
1667
|
+
*/
|
|
1668
|
+
maxNotes?: number;
|
|
1669
|
+
/**
|
|
1670
|
+
* How many statements a cell needs before it is reported.
|
|
1671
|
+
*
|
|
1672
|
+
* @defaultValue 2
|
|
1673
|
+
*/
|
|
1674
|
+
minOccurrences?: number;
|
|
1675
|
+
/**
|
|
1676
|
+
* Upper bound on the work this call may do.
|
|
1677
|
+
*
|
|
1678
|
+
* @defaultValue {@link DEFAULT_GENERATION_BUDGET}
|
|
1679
|
+
*/
|
|
1680
|
+
budget?: number;
|
|
1681
|
+
};
|
|
1682
|
+
/**
|
|
1683
|
+
* Find the cells a melody keeps coming back to.
|
|
1684
|
+
*
|
|
1685
|
+
* Every window of `minNotes` to `maxNotes` consecutive notes is reduced to its
|
|
1686
|
+
* interval sequence and its rhythmic profile, and windows sharing both are
|
|
1687
|
+
* statements of one motif — so a restatement a fifth higher, or one written in
|
|
1688
|
+
* doubled note values, is found as the same cell rather than as a new one.
|
|
1689
|
+
* Overlapping statements of a repetitive figure are counted once, and a cell
|
|
1690
|
+
* whose statements all sit inside the statements of a longer cell that recurs at
|
|
1691
|
+
* least as often is dropped, so the answer names the longest thing that recurs
|
|
1692
|
+
* rather than every fragment of it.
|
|
1693
|
+
*
|
|
1694
|
+
* The melody is expected to be monophonic, as {@link analyzeVoice} expects a
|
|
1695
|
+
* voice to be; split polyphonic material into lines first. Notes struck together
|
|
1696
|
+
* are read as one event, the highest of them standing for it, so a chord is
|
|
1697
|
+
* reduced to its top voice rather than read as a line of its own. Onsets are
|
|
1698
|
+
* expected to be quantised, since two statements must agree on their rhythm to
|
|
1699
|
+
* be recognised as one motif.
|
|
1700
|
+
*
|
|
1701
|
+
* @param notes The melody, in time order. Notes that never sound are dropped.
|
|
1702
|
+
* @param opts Cell-length bounds and the recurrence threshold; see
|
|
1703
|
+
* {@link ExtractMotifsOptions}.
|
|
1704
|
+
* @returns The motifs found, longest first, then by how often they recur, then
|
|
1705
|
+
* by where they first appear. Empty when nothing recurs.
|
|
1706
|
+
* @example
|
|
1707
|
+
* ```ts
|
|
1708
|
+
* import { extractMotifs } from '@libraz/libcantus';
|
|
1709
|
+
* const notes = [
|
|
1710
|
+
* { pitch: 60, startBeat: 0, durationBeat: 1 },
|
|
1711
|
+
* { pitch: 62, startBeat: 1, durationBeat: 1 },
|
|
1712
|
+
* { pitch: 64, startBeat: 2, durationBeat: 1 },
|
|
1713
|
+
* { pitch: 67, startBeat: 4, durationBeat: 1 },
|
|
1714
|
+
* { pitch: 69, startBeat: 5, durationBeat: 1 },
|
|
1715
|
+
* { pitch: 71, startBeat: 6, durationBeat: 1 },
|
|
1716
|
+
* ];
|
|
1717
|
+
* const motifs = extractMotifs(notes);
|
|
1718
|
+
* motifs[0]?.occurrences.map((o) => o.startBeat); // [0, 4]
|
|
1719
|
+
* ```
|
|
1720
|
+
* @category Arrangement & Analysis
|
|
1721
|
+
*/
|
|
1722
|
+
declare function extractMotifs(notes: readonly NoteEvent[], opts?: ExtractMotifsOptions): MotifData[];
|
|
1723
|
+
/**
|
|
1724
|
+
* Read a run of notes as a single-statement motif.
|
|
1725
|
+
*
|
|
1726
|
+
* {@link extractMotifs} answers with motifs it found recurring; this is how a
|
|
1727
|
+
* caller names one it already has — a subject, an answer, a phrase lifted out of
|
|
1728
|
+
* a score — so that it can be handed to {@link relateMotifs}.
|
|
1729
|
+
*
|
|
1730
|
+
* The cell is expected to be monophonic, as {@link analyzeVoice} expects a voice
|
|
1731
|
+
* to be. Notes struck together are read as one event, the highest of them
|
|
1732
|
+
* standing for it, so a chord is reduced to its top voice rather than read as a
|
|
1733
|
+
* line of its own.
|
|
1734
|
+
*
|
|
1735
|
+
* @param notes The cell, in time order. Notes that never sound are dropped, and
|
|
1736
|
+
* notes sharing an onset are folded to their top voice.
|
|
1737
|
+
* @returns The motif, carrying exactly one occurrence.
|
|
1738
|
+
* @example
|
|
1739
|
+
* ```ts
|
|
1740
|
+
* import { motifFromNotes, relateMotifs } from '@libraz/libcantus';
|
|
1741
|
+
* const subject = motifFromNotes([
|
|
1742
|
+
* { pitch: 60, startBeat: 0, durationBeat: 1 },
|
|
1743
|
+
* { pitch: 62, startBeat: 1, durationBeat: 1 },
|
|
1744
|
+
* { pitch: 64, startBeat: 2, durationBeat: 1 },
|
|
1745
|
+
* ]);
|
|
1746
|
+
* const answer = motifFromNotes([
|
|
1747
|
+
* { pitch: 67, startBeat: 3, durationBeat: 1 },
|
|
1748
|
+
* { pitch: 69, startBeat: 4, durationBeat: 1 },
|
|
1749
|
+
* { pitch: 71, startBeat: 5, durationBeat: 1 },
|
|
1750
|
+
* ]);
|
|
1751
|
+
* relateMotifs(subject, answer)?.kind; // 'transposition'
|
|
1752
|
+
* ```
|
|
1753
|
+
* @category Arrangement & Analysis
|
|
1754
|
+
*/
|
|
1755
|
+
declare function motifFromNotes(notes: readonly NoteEvent[]): MotifData;
|
|
1756
|
+
|
|
1757
|
+
/**
|
|
1758
|
+
* What every reading of a melody has to agree on first.
|
|
1759
|
+
*
|
|
1760
|
+
* A melody is compared, named and classified by three modules here, and all
|
|
1761
|
+
* three start from the same two questions: which notes sound, in what order,
|
|
1762
|
+
* and what the gaps between their onsets are. Answered separately they would
|
|
1763
|
+
* drift — one reading folding a chord to its top voice and another not — so
|
|
1764
|
+
* they are answered once, here.
|
|
1765
|
+
*/
|
|
1766
|
+
|
|
1767
|
+
/**
|
|
1768
|
+
* Anything that can be read as a melodic line: a motif, or plain note events.
|
|
1769
|
+
*
|
|
1770
|
+
* @category Arrangement & Analysis
|
|
1771
|
+
*/
|
|
1772
|
+
type MelodicPhrase = MotifData | readonly NoteEvent[];
|
|
1773
|
+
|
|
1774
|
+
/**
|
|
1775
|
+
* The shape of a line: which way it moves, and what that adds up to.
|
|
1776
|
+
*
|
|
1777
|
+
* A contour is the melody with its pitches forgotten — the sequence of ups and
|
|
1778
|
+
* downs alone — which is what lets a phrase be called an arch whatever key it
|
|
1779
|
+
* is in and whatever intervals it is built from.
|
|
1780
|
+
*/
|
|
1781
|
+
|
|
1782
|
+
/**
|
|
1783
|
+
* Step direction between two consecutive notes.
|
|
1784
|
+
*
|
|
1785
|
+
* @category Arrangement & Analysis
|
|
1786
|
+
*/
|
|
1787
|
+
type ContourDirection = 'up' | 'down' | 'same';
|
|
1788
|
+
/**
|
|
1789
|
+
* The overall shapes a line can be read as.
|
|
1790
|
+
*
|
|
1791
|
+
* @category Arrangement & Analysis
|
|
1792
|
+
*/
|
|
1793
|
+
declare const MELODIC_CONTOUR_SHAPES: readonly ["arch", "ascending", "descending", "wave", "static"];
|
|
1794
|
+
/**
|
|
1795
|
+
* The overall shape of a line.
|
|
1796
|
+
*
|
|
1797
|
+
* The first four names are the vocabulary the motif generator's contours are
|
|
1798
|
+
* written in, and mean the same here. `'static'` is the shape a generator never
|
|
1799
|
+
* asks for and an analysis regularly meets: a line that does not move. A line
|
|
1800
|
+
* that dips and comes back — an arch upside down — reads as `'wave'`, since the
|
|
1801
|
+
* shared vocabulary has no name of its own for it.
|
|
1802
|
+
*
|
|
1803
|
+
* A wave has to turn more than once to be heard as one, so a cell the generator
|
|
1804
|
+
* writes for `'wave'` reads back as `'wave'` only from three bars up; the one-
|
|
1805
|
+
* and two-bar cells turn once and read as `'arch'`. The other three shapes come
|
|
1806
|
+
* back under their own name at every length.
|
|
1807
|
+
*
|
|
1808
|
+
* @category Arrangement & Analysis
|
|
1809
|
+
*/
|
|
1810
|
+
type MelodicContourShape = (typeof MELODIC_CONTOUR_SHAPES)[number];
|
|
1811
|
+
/**
|
|
1812
|
+
* The abstract shape of a line: its step directions and what they add up to.
|
|
1813
|
+
*
|
|
1814
|
+
* @category Arrangement & Analysis
|
|
1815
|
+
*/
|
|
1816
|
+
type MelodicContour = {
|
|
1817
|
+
/** One direction per adjacent pair of notes, in time order. */
|
|
1818
|
+
directions: ContourDirection[];
|
|
1819
|
+
/** What the directions add up to. */
|
|
1820
|
+
shape: MelodicContourShape;
|
|
1821
|
+
/** Index of the highest note; ties keep the earliest, and -1 for a line with no notes. */
|
|
1822
|
+
peakIndex: number;
|
|
1823
|
+
/** Index of the lowest note; ties keep the earliest, and -1 for a line with no notes. */
|
|
1824
|
+
troughIndex: number;
|
|
1825
|
+
/** Semitone distance from the lowest note to the highest. */
|
|
1826
|
+
range: number;
|
|
1827
|
+
/** Why the line was given that shape. */
|
|
1828
|
+
rationale: string;
|
|
1829
|
+
};
|
|
1830
|
+
/**
|
|
1831
|
+
* Read the shape of a line.
|
|
1832
|
+
*
|
|
1833
|
+
* The step directions are the literal answer; the shape is what they add up to.
|
|
1834
|
+
* A line is called ascending or descending when most of its motion runs one way,
|
|
1835
|
+
* not only when every step does — a climb with one dip in it is still heard as a
|
|
1836
|
+
* climb — and an arch when it rises to an interior peak and comes back down.
|
|
1837
|
+
* Anything that keeps changing direction is a wave, and a line that does not move
|
|
1838
|
+
* is static.
|
|
1839
|
+
*
|
|
1840
|
+
* The line is expected to be monophonic, as {@link analyzeVoice} expects a voice
|
|
1841
|
+
* to be; split polyphonic material into lines first. Notes struck together are
|
|
1842
|
+
* read as one event, the highest of them standing for it — a chord and the note
|
|
1843
|
+
* after it trace one step, not a climb through the chord — so a piano part read
|
|
1844
|
+
* whole answers for its top voice rather than for a line no one plays.
|
|
1845
|
+
*
|
|
1846
|
+
* @param notes The line: a motif, or plain note events. Notes that never sound
|
|
1847
|
+
* are dropped, and notes sharing an onset are folded to their top voice.
|
|
1848
|
+
* @returns The directions, the shape, the peak and trough, and a rationale. A
|
|
1849
|
+
* line with no sounding notes is static with a range of 0, and its peak and
|
|
1850
|
+
* trough are -1: there is no note for them to point at.
|
|
1851
|
+
* @example
|
|
1852
|
+
* ```ts
|
|
1853
|
+
* import { melodicContour } from '@libraz/libcantus';
|
|
1854
|
+
* const notes = [
|
|
1855
|
+
* { pitch: 60, startBeat: 0, durationBeat: 1 },
|
|
1856
|
+
* { pitch: 64, startBeat: 1, durationBeat: 1 },
|
|
1857
|
+
* { pitch: 60, startBeat: 2, durationBeat: 1 },
|
|
1858
|
+
* ];
|
|
1859
|
+
* melodicContour(notes).shape; // 'arch'
|
|
1860
|
+
* ```
|
|
1861
|
+
* @category Arrangement & Analysis
|
|
1862
|
+
*/
|
|
1863
|
+
declare function melodicContour(notes: MelodicPhrase): MelodicContour;
|
|
1864
|
+
|
|
1865
|
+
/**
|
|
1866
|
+
* The transformation between two statements of a motif, named.
|
|
1867
|
+
*
|
|
1868
|
+
* Two cells stand in a relation when one is the other put through a device the
|
|
1869
|
+
* repertoire has a name for — repetition, transposition, inversion, retrograde,
|
|
1870
|
+
* augmentation — and naming it is what turns a pair of similar phrases into an
|
|
1871
|
+
* account of how the second was made from the first.
|
|
1872
|
+
*/
|
|
1873
|
+
|
|
1874
|
+
/**
|
|
1875
|
+
* The named transformations {@link relateMotifs} can report between two motif
|
|
1876
|
+
* statements.
|
|
1877
|
+
*
|
|
1878
|
+
* @category Arrangement & Analysis
|
|
1879
|
+
*/
|
|
1880
|
+
declare const MOTIF_RELATION_KINDS: readonly ["repetition", "transposition", "tonalTransposition", "inversion", "retrograde", "retrogradeInversion", "augmentation", "diminution"];
|
|
1881
|
+
/**
|
|
1882
|
+
* How one statement of a motif stands to another.
|
|
1883
|
+
*
|
|
1884
|
+
* `'transposition'` is the literal one — every interval preserved, which is what
|
|
1885
|
+
* makes a sequence built on it a *real* sequence. `'tonalTransposition'` shifts
|
|
1886
|
+
* by scale degrees instead and lets the key resize the intervals, which is what
|
|
1887
|
+
* makes a sequence built on it a *tonal* sequence; the two are different devices
|
|
1888
|
+
* and are never reported as one. `'augmentation'` and `'diminution'` name the
|
|
1889
|
+
* relation only when the pitches are untouched, so an inversion in doubled note
|
|
1890
|
+
* values reads as `'inversion'` with a `timeRatio` of 2 rather than losing the
|
|
1891
|
+
* inversion to the stretch.
|
|
1892
|
+
*
|
|
1893
|
+
* @category Arrangement & Analysis
|
|
1894
|
+
*/
|
|
1895
|
+
type MotifRelationKind = (typeof MOTIF_RELATION_KINDS)[number];
|
|
1896
|
+
/**
|
|
1897
|
+
* The transformation that turns one motif into another.
|
|
1898
|
+
*
|
|
1899
|
+
* @category Arrangement & Analysis
|
|
1900
|
+
*/
|
|
1901
|
+
type MotifRelation = {
|
|
1902
|
+
/** The named transformation. */
|
|
1903
|
+
kind: MotifRelationKind;
|
|
1904
|
+
/**
|
|
1905
|
+
* Whether the second statement begins where the first ends, which is what
|
|
1906
|
+
* separates a sequence from a restatement elsewhere in the piece: a
|
|
1907
|
+
* `'transposition'` that is one is a real sequence, a `'tonalTransposition'`
|
|
1908
|
+
* that is one is a tonal sequence.
|
|
1909
|
+
*/
|
|
1910
|
+
sequence: boolean;
|
|
1911
|
+
/** Semitones from the first statement's first note to the second's. */
|
|
1912
|
+
semitones: number;
|
|
1913
|
+
/** The same distance named as a spelled interval. */
|
|
1914
|
+
interval: SpelledInterval;
|
|
1915
|
+
/** Scale degrees the second statement stands above the first, when tonal. */
|
|
1916
|
+
degrees?: number;
|
|
1917
|
+
/**
|
|
1918
|
+
* How much the second statement is stretched against the first: 2 for doubled
|
|
1919
|
+
* note values, 0.5 for halved, 1 for unchanged.
|
|
1920
|
+
*
|
|
1921
|
+
* Measured in the direction the relation names, so a retrograde that kept
|
|
1922
|
+
* every note value reports 1 however uneven those values are: it is compared
|
|
1923
|
+
* against the model played backwards, not against the model as written.
|
|
1924
|
+
*/
|
|
1925
|
+
timeRatio: number;
|
|
1926
|
+
/** Why the pair was given that name. */
|
|
1927
|
+
rationale: string;
|
|
1928
|
+
};
|
|
1929
|
+
/**
|
|
1930
|
+
* The part of a {@link MotifRelation} that names the transformation itself,
|
|
1931
|
+
* without the rationale prose that explains it.
|
|
1932
|
+
*
|
|
1933
|
+
* @category Arrangement & Analysis
|
|
1934
|
+
*/
|
|
1935
|
+
type MotifRelationSummary = Pick<MotifRelation, 'kind' | 'sequence' | 'semitones' | 'degrees' | 'timeRatio'>;
|
|
1936
|
+
/**
|
|
1937
|
+
* Name how two statements of a motif relate.
|
|
1938
|
+
*
|
|
1939
|
+
* The two are compared as shapes, not as pitches: the interval sequences say
|
|
1940
|
+
* which transformations could name the pair and the onset gaps say which of
|
|
1941
|
+
* them does, so a statement a fourth higher in doubled note values is
|
|
1942
|
+
* recognised for what it is, and a cell that reads as both an inversion and a
|
|
1943
|
+
* retrograde is named by the way its rhythm runs rather than by which name came
|
|
1944
|
+
* to hand first. An evenly timed cell runs the same both ways, so there the
|
|
1945
|
+
* reading that needs no transposition wins: a cell played backwards on its own
|
|
1946
|
+
* pitches is a retrograde. A pair whose rhythms correspond in neither direction — the same
|
|
1947
|
+
* way round for a repetition or a transposition, the model played backwards for
|
|
1948
|
+
* a retrograde, note values and all — is not a transformation of the motif but a
|
|
1949
|
+
* different figure, and answers null; {@link melodicSimilarity} is what scores
|
|
1950
|
+
* those.
|
|
1951
|
+
*
|
|
1952
|
+
* With a `key` in hand the search also asks whether the second statement is the
|
|
1953
|
+
* first moved by scale degrees rather than by semitones. That is the tonal
|
|
1954
|
+
* answer to the real one, and the two are kept apart: a real transposition keeps
|
|
1955
|
+
* every interval literally, a tonal one lets the key resize them, so a subject
|
|
1956
|
+
* answered a step higher reads as `'transposition'` when its major second stays
|
|
1957
|
+
* major and as `'tonalTransposition'` when the scale turns it minor.
|
|
1958
|
+
*
|
|
1959
|
+
* @param a The model statement.
|
|
1960
|
+
* @param b The statement to name against it.
|
|
1961
|
+
* @param keyLike Key context for the tonal reading. Without one that reading is
|
|
1962
|
+
* unavailable, and a statement holding only diatonically is left unnamed
|
|
1963
|
+
* unless its interval pattern also fits a member of the retrograde family, in
|
|
1964
|
+
* which case it is named there: a triad restated a degree higher swaps two
|
|
1965
|
+
* adjacent interval sizes, which is what a retrograde inversion does to it as
|
|
1966
|
+
* well, and equal note values read the same way round in both directions, so
|
|
1967
|
+
* the notes alone cannot separate the two. A key separates them.
|
|
1968
|
+
* @returns The relation, or null when the two stand in none.
|
|
1969
|
+
* @example
|
|
1970
|
+
* ```ts
|
|
1971
|
+
* import { majorKey, motifFromNotes, relateMotifs } from '@libraz/libcantus';
|
|
1972
|
+
* const model = motifFromNotes([
|
|
1973
|
+
* { pitch: 60, startBeat: 0, durationBeat: 1 },
|
|
1974
|
+
* { pitch: 62, startBeat: 1, durationBeat: 1 },
|
|
1975
|
+
* { pitch: 64, startBeat: 2, durationBeat: 1 },
|
|
1976
|
+
* ]);
|
|
1977
|
+
* const answer = motifFromNotes([
|
|
1978
|
+
* { pitch: 62, startBeat: 3, durationBeat: 1 },
|
|
1979
|
+
* { pitch: 64, startBeat: 4, durationBeat: 1 },
|
|
1980
|
+
* { pitch: 65, startBeat: 5, durationBeat: 1 },
|
|
1981
|
+
* ]);
|
|
1982
|
+
* relateMotifs(model, answer, majorKey(0))?.kind; // 'tonalTransposition'
|
|
1983
|
+
* ```
|
|
1984
|
+
* @category Arrangement & Analysis
|
|
1985
|
+
*/
|
|
1986
|
+
declare function relateMotifs(a: MotifData, b: MotifData, keyLike?: SpelledKeyLike): MotifRelation | null;
|
|
1987
|
+
|
|
1988
|
+
/**
|
|
1989
|
+
* How the statements of a melody's motifs derive from one another.
|
|
1990
|
+
*
|
|
1991
|
+
* {@link extractMotifs} groups statements into motifs; this reads across that
|
|
1992
|
+
* grouping and asks, for every statement after the first, which earlier
|
|
1993
|
+
* statement it most plausibly grew out of. The answer is a forest rather than a
|
|
1994
|
+
* graph proper — every statement has at most one parent — because a derivation
|
|
1995
|
+
* only ever has one source, however many statements it could be heard against.
|
|
1996
|
+
*/
|
|
1997
|
+
|
|
1998
|
+
/**
|
|
1999
|
+
* Options controlling {@link motifGraph}.
|
|
2000
|
+
*
|
|
2001
|
+
* @category Arrangement & Analysis
|
|
2002
|
+
*/
|
|
2003
|
+
type MotifGraphOptions = {
|
|
2004
|
+
/** Key context for the tonal reading `relateMotifs` can offer. */
|
|
2005
|
+
key?: SpelledKeyLike;
|
|
2006
|
+
/**
|
|
2007
|
+
* Lower bound on `melodicSimilarity` for a pair with no named transformation
|
|
2008
|
+
* to still be drawn as a variation.
|
|
2009
|
+
*
|
|
2010
|
+
* @defaultValue 0.75
|
|
2011
|
+
*/
|
|
2012
|
+
variationThreshold?: number;
|
|
2013
|
+
/**
|
|
2014
|
+
* Upper bound on the work this call may do.
|
|
2015
|
+
*
|
|
2016
|
+
* @defaultValue {@link DEFAULT_GENERATION_BUDGET}
|
|
2017
|
+
*/
|
|
2018
|
+
budget?: number;
|
|
2019
|
+
};
|
|
2020
|
+
/**
|
|
2021
|
+
* One statement of a motif, as a node of {@link MotifGraph}.
|
|
2022
|
+
*
|
|
2023
|
+
* @category Arrangement & Analysis
|
|
2024
|
+
*/
|
|
2025
|
+
type MotifGraphNode = {
|
|
2026
|
+
/** Index into the `motifs` array this statement belongs to. */
|
|
2027
|
+
motif: number;
|
|
2028
|
+
/** Index into that motif's `occurrences`. */
|
|
2029
|
+
occurrence: number;
|
|
2030
|
+
/** Onset of the statement's first note. */
|
|
2031
|
+
startBeat: number;
|
|
2032
|
+
/** End of the statement's last note, exclusive. */
|
|
2033
|
+
endBeat: number;
|
|
2034
|
+
};
|
|
2035
|
+
/**
|
|
2036
|
+
* The derivation drawn from one statement to a later one.
|
|
2037
|
+
*
|
|
2038
|
+
* @category Arrangement & Analysis
|
|
2039
|
+
*/
|
|
2040
|
+
type MotifGraphEdge = {
|
|
2041
|
+
/** Index of the preceding node this statement derives from. */
|
|
2042
|
+
from: number;
|
|
2043
|
+
/** Index of the derived node. */
|
|
2044
|
+
to: number;
|
|
2045
|
+
/** The named transformation, or null when none explains the pair. */
|
|
2046
|
+
relation: MotifRelationSummary | null;
|
|
2047
|
+
/** `melodicSimilarity` between the two statements. */
|
|
2048
|
+
similarity: number;
|
|
2049
|
+
};
|
|
2050
|
+
/**
|
|
2051
|
+
* How a melody's motif statements derive from one another.
|
|
2052
|
+
*
|
|
2053
|
+
* @category Arrangement & Analysis
|
|
2054
|
+
*/
|
|
2055
|
+
type MotifGraph = {
|
|
2056
|
+
/** Every statement of every motif, ordered by `startBeat` then by `motif`. */
|
|
2057
|
+
nodes: MotifGraphNode[];
|
|
2058
|
+
/**
|
|
2059
|
+
* The derivation drawn to each node from an earlier one, ordered by `to`.
|
|
2060
|
+
* Every node has at most one edge into it, so the edges describe a forest.
|
|
2061
|
+
*/
|
|
2062
|
+
edges: MotifGraphEdge[];
|
|
2063
|
+
};
|
|
2064
|
+
/**
|
|
2065
|
+
* Read a melody's motif statements as a derivation forest.
|
|
2066
|
+
*
|
|
2067
|
+
* Every statement after the first is compared against every statement that
|
|
2068
|
+
* precedes it: the pair {@link relateMotifs} can name outranks any it cannot,
|
|
2069
|
+
* the closest-scoring precedent among equals outranks the rest, and a
|
|
2070
|
+
* statement whose best precedent is neither named nor close enough by
|
|
2071
|
+
* `melodicSimilarity` is a root — new material, not a derivation of what came
|
|
2072
|
+
* before it. The derivation traced this way explains a subject restated,
|
|
2073
|
+
* transposed, inverted, augmented, or loosely varied by what it grew out of,
|
|
2074
|
+
* and leaves a truly new idea unattached rather than forcing it onto whatever
|
|
2075
|
+
* came earliest.
|
|
2076
|
+
*
|
|
2077
|
+
* `motifs` is read against `line` rather than against its own prime
|
|
2078
|
+
* statements: an occurrence's notes can differ from the motif's first
|
|
2079
|
+
* statement in duration even where their intervals and onset gaps agree, and a
|
|
2080
|
+
* retrograde reading depends on that duration. So every occurrence is read
|
|
2081
|
+
* back off `line` and named fresh, occurrence to occurrence.
|
|
2082
|
+
*
|
|
2083
|
+
* @param line The melody `motifs` was extracted from. Notes that never sound
|
|
2084
|
+
* are dropped, exactly as {@link extractMotifs} drops them, so the two agree
|
|
2085
|
+
* on which note an occurrence's `noteIndex` addresses.
|
|
2086
|
+
* @param motifs The motifs to graph, as {@link extractMotifs} reports them.
|
|
2087
|
+
* @param opts Key context, the variation threshold, and a work budget; see
|
|
2088
|
+
* {@link MotifGraphOptions}.
|
|
2089
|
+
* @returns The statements as nodes, and the derivation drawn to each from an
|
|
2090
|
+
* earlier one.
|
|
2091
|
+
* @example
|
|
2092
|
+
* ```ts
|
|
2093
|
+
* import { extractMotifs, motifGraph } from '@libraz/libcantus';
|
|
2094
|
+
* const notes = [
|
|
2095
|
+
* { pitch: 60, startBeat: 0, durationBeat: 1 },
|
|
2096
|
+
* { pitch: 62, startBeat: 1, durationBeat: 1 },
|
|
2097
|
+
* { pitch: 64, startBeat: 2, durationBeat: 1 },
|
|
2098
|
+
* { pitch: 67, startBeat: 4, durationBeat: 1 },
|
|
2099
|
+
* { pitch: 69, startBeat: 5, durationBeat: 1 },
|
|
2100
|
+
* { pitch: 71, startBeat: 6, durationBeat: 1 },
|
|
2101
|
+
* ];
|
|
2102
|
+
* const graph = motifGraph(notes, extractMotifs(notes));
|
|
2103
|
+
* graph.edges[0]?.relation?.kind; // 'transposition'
|
|
2104
|
+
* ```
|
|
2105
|
+
* @category Arrangement & Analysis
|
|
2106
|
+
*/
|
|
2107
|
+
declare function motifGraph(line: readonly NoteEvent[], motifs: readonly MotifData[], opts?: MotifGraphOptions): MotifGraph;
|
|
2108
|
+
|
|
2109
|
+
/**
|
|
2110
|
+
* Harmonic reduction: which chords carry the progression and which decorate it.
|
|
2111
|
+
*
|
|
2112
|
+
* `analyzeVoice` can say that a note is a passing tone; a timeline is flat, so
|
|
2113
|
+
* nothing could say the same of a chord. This is that answer one level up — the
|
|
2114
|
+
* middle chord of `Cmaj7 - C#dim7 - Dm7` is an embellishment, and the frame
|
|
2115
|
+
* under `I - IV - #ivo7 - V - I` is `I - IV - V - I`.
|
|
2116
|
+
*
|
|
2117
|
+
* **The position taken here.** What counts as structural is a theoretical
|
|
2118
|
+
* choice, not a fact, and this module makes the functional one: *a chord is
|
|
2119
|
+
* structural unless it is demonstrably an embellishment of its neighbours*. The
|
|
2120
|
+
* frame is what carries harmonic function in the prevailing key — the tonic, the
|
|
2121
|
+
* dominant, and the chords that cadence — so those are never reduced away; a
|
|
2122
|
+
* chord that tonicizes something other than the tonic is prolonging, not
|
|
2123
|
+
* framing, however dominant its sonority. Everything else keeps its place unless
|
|
2124
|
+
* its root traces one of two figures against the chords around it, the same two
|
|
2125
|
+
* figures {@link analyzeVoice} matches at the note level: a step through
|
|
2126
|
+
* (passing) and a step away and back (neighbor). Defaulting to structural, and
|
|
2127
|
+
* demoting only on evidence, is what keeps a reduction from quietly deleting
|
|
2128
|
+
* harmony it merely failed to recognize.
|
|
2129
|
+
*
|
|
2130
|
+
* The salience reading — that the frame is whatever lasts longest, regardless of
|
|
2131
|
+
* function — is the main alternative, and it is a live one for repertoire where
|
|
2132
|
+
* function is weak. {@link ReduceProgressionOptions.basis} switches to it: the
|
|
2133
|
+
* figures stay the same, only what protects a chord from them changes.
|
|
2134
|
+
*
|
|
2135
|
+
* Both readings are deterministic: the same timeline and key always reduce the
|
|
2136
|
+
* same way.
|
|
2137
|
+
*/
|
|
2138
|
+
|
|
2139
|
+
/**
|
|
2140
|
+
* The places a chord can hold in a progression.
|
|
2141
|
+
*
|
|
2142
|
+
* @category Arrangement & Analysis
|
|
2143
|
+
*/
|
|
2144
|
+
declare const REDUCTION_LEVELS: readonly ["structural", "passing", "neighbor"];
|
|
2145
|
+
/**
|
|
2146
|
+
* The place a chord holds in a progression.
|
|
2147
|
+
*
|
|
2148
|
+
* `'structural'` is the frame; `'passing'` and `'neighbor'` are the two
|
|
2149
|
+
* embellishing figures, spelled exactly as {@link TheoryLabel} spells them for
|
|
2150
|
+
* a note, so one legend covers both levels of analysis.
|
|
2151
|
+
*
|
|
2152
|
+
* @category Arrangement & Analysis
|
|
2153
|
+
*/
|
|
2154
|
+
type ReductionLevel = (typeof REDUCTION_LEVELS)[number];
|
|
2155
|
+
/**
|
|
2156
|
+
* A chord with the place it holds, the beats it holds it for, and a short
|
|
2157
|
+
* rationale.
|
|
2158
|
+
*
|
|
2159
|
+
* One entry per timeline segment, in the same order. The entry carries the
|
|
2160
|
+
* segment's own beat range, so the chords that survive a filter still say when
|
|
2161
|
+
* they sound: holding the structural chords fixed is what a reharmonizer needs,
|
|
2162
|
+
* and it cannot hold a chord at a place the filter threw away.
|
|
2163
|
+
*
|
|
2164
|
+
* @category Arrangement & Analysis
|
|
2165
|
+
*/
|
|
2166
|
+
type ReducedChord = {
|
|
2167
|
+
chord: Chord;
|
|
2168
|
+
startBeat: number;
|
|
2169
|
+
endBeat: number;
|
|
2170
|
+
level: ReductionLevel;
|
|
2171
|
+
rationale: string;
|
|
2172
|
+
};
|
|
2173
|
+
/**
|
|
2174
|
+
* What a reduction treats as the frame.
|
|
2175
|
+
*
|
|
2176
|
+
* `'function'` is the functional reading: the tonic, the dominant and the
|
|
2177
|
+
* chords that cadence are the frame. `'duration'` is the salience reading: a
|
|
2178
|
+
* chord is the frame when it outlasts the chords around it — its length beats
|
|
2179
|
+
* the median of the other chords' — whatever function it carries. Nothing
|
|
2180
|
+
* outlasts anything in an even harmonic rhythm, so a loop or a vamp protects no
|
|
2181
|
+
* chord by length and the two figures decide, as they do under either reading.
|
|
2182
|
+
*
|
|
2183
|
+
* @category Arrangement & Analysis
|
|
2184
|
+
*/
|
|
2185
|
+
type ReductionBasis = 'function' | 'duration';
|
|
2186
|
+
/**
|
|
2187
|
+
* Options for {@link reduceProgression}.
|
|
2188
|
+
*
|
|
2189
|
+
* @category Arrangement & Analysis
|
|
2190
|
+
*/
|
|
2191
|
+
type ReduceProgressionOptions = {
|
|
2192
|
+
/**
|
|
2193
|
+
* Which reading decides what the frame is; see {@link ReductionBasis}.
|
|
2194
|
+
*
|
|
2195
|
+
* @defaultValue `'function'`
|
|
2196
|
+
*/
|
|
2197
|
+
basis?: ReductionBasis;
|
|
2198
|
+
};
|
|
2199
|
+
/**
|
|
2200
|
+
* Reduce a chord progression to its frame, labelling every chord.
|
|
2201
|
+
*
|
|
2202
|
+
* One entry comes back per timeline segment, in the same order, so the two read
|
|
2203
|
+
* in step. Filtering the result to `'structural'` is the skeleton view — the
|
|
2204
|
+
* `I - IV - V - I` under a progression that spells far more chords than that —
|
|
2205
|
+
* and holding those chords fixed is what a reharmonizer needs in order to
|
|
2206
|
+
* rewrite the surface without moving the harmony. Each entry carries its own
|
|
2207
|
+
* `startBeat` and `endBeat`, so a filtered chord still knows where it sounds
|
|
2208
|
+
* once the segments it was read against are gone.
|
|
2209
|
+
*
|
|
2210
|
+
* A chord is structural unless one of two figures demotes it: its root stepping
|
|
2211
|
+
* in from the previous chord and on to the next in the same direction (passing),
|
|
2212
|
+
* or stepping away from a harmony that returns (neighbor). Chords carrying the
|
|
2213
|
+
* frame are never demoted, and what carries the frame is the module's stated
|
|
2214
|
+
* theoretical position — see {@link ReductionBasis} for the reading this takes
|
|
2215
|
+
* by default and the one it can be switched to.
|
|
2216
|
+
*
|
|
2217
|
+
* Chords separated by a rest form no figure across it, the way
|
|
2218
|
+
* {@link detectCadences} pairs no chords across one.
|
|
2219
|
+
*
|
|
2220
|
+
* @param timeline The chord timeline to reduce.
|
|
2221
|
+
* @param key The prevailing key, or the key in force at a given beat, for music
|
|
2222
|
+
* that modulates.
|
|
2223
|
+
* @param opts Which reading decides the frame; see
|
|
2224
|
+
* {@link ReduceProgressionOptions}.
|
|
2225
|
+
* @returns One labelled chord per segment, in time order.
|
|
2226
|
+
* @throws If `opts.basis` is not one of the readings {@link ReductionBasis}
|
|
2227
|
+
* names.
|
|
2228
|
+
* @example
|
|
2229
|
+
* ```ts
|
|
2230
|
+
* import { chordTimelineFromChords, majorKey, reduceProgression } from '@libraz/libcantus';
|
|
2231
|
+
* const timeline = chordTimelineFromChords(
|
|
2232
|
+
* [
|
|
2233
|
+
* { rootPc: 0, quality: 'maj7', startBeat: 0 },
|
|
2234
|
+
* { rootPc: 1, quality: 'dim7', startBeat: 4 },
|
|
2235
|
+
* { rootPc: 2, quality: 'min7', startBeat: 8 },
|
|
2236
|
+
* ],
|
|
2237
|
+
* 12,
|
|
2238
|
+
* );
|
|
2239
|
+
* reduceProgression(timeline, majorKey(0)).map((entry) => entry.level);
|
|
2240
|
+
* // ['structural', 'passing', 'structural']
|
|
2241
|
+
* ```
|
|
2242
|
+
* @category Arrangement & Analysis
|
|
2243
|
+
*/
|
|
2244
|
+
declare function reduceProgression(timeline: ChordTimeline, key: KeyContext, opts?: ReduceProgressionOptions): ReducedChord[];
|
|
2245
|
+
|
|
2246
|
+
/**
|
|
2247
|
+
* Where a line places its onsets against the meter: how dense they are, which
|
|
2248
|
+
* metric positions they favour, and how far they push against the beat.
|
|
2249
|
+
*
|
|
2250
|
+
* A phrase and a whole piece are read the same way — a run of onsets over a
|
|
2251
|
+
* span of beats — so a single reading serves both a melodic line and a
|
|
2252
|
+
* harmonic-rhythm reading of chord changes turned into onsets of their own.
|
|
2253
|
+
*/
|
|
2254
|
+
|
|
2255
|
+
/**
|
|
2256
|
+
* Options for {@link analyzeRhythm}.
|
|
2257
|
+
*
|
|
2258
|
+
* @category Arrangement & Analysis
|
|
2259
|
+
*/
|
|
2260
|
+
type RhythmAnalysisOptions = {
|
|
2261
|
+
/**
|
|
2262
|
+
* A single time signature held across the whole span, as sugar for a
|
|
2263
|
+
* one-element `meters`; defaults to 4/4. Giving both is an input error.
|
|
2264
|
+
*
|
|
2265
|
+
* @defaultValue `4/4`
|
|
2266
|
+
*/
|
|
2267
|
+
ts?: MeterLike;
|
|
2268
|
+
/**
|
|
2269
|
+
* The meter as it changes over the span, so a piece that changes metre is
|
|
2270
|
+
* read against its own bar lines throughout.
|
|
2271
|
+
*
|
|
2272
|
+
* @defaultValue 4/4 throughout
|
|
2273
|
+
*/
|
|
2274
|
+
meters?: MeterLike;
|
|
2275
|
+
/**
|
|
2276
|
+
* End of the analysed span in beats; defaults to the end of the last note.
|
|
2277
|
+
*
|
|
2278
|
+
* @defaultValue the end of the last note
|
|
2279
|
+
*/
|
|
2280
|
+
totalBeats?: number;
|
|
2281
|
+
/**
|
|
2282
|
+
* Upper bound on the work this call may do.
|
|
2283
|
+
*
|
|
2284
|
+
* @defaultValue {@link DEFAULT_GENERATION_BUDGET}
|
|
2285
|
+
*/
|
|
2286
|
+
budget?: number;
|
|
2287
|
+
};
|
|
2288
|
+
/**
|
|
2289
|
+
* How a line's onsets sit against one time signature: which slot of its bar
|
|
2290
|
+
* they favour, mass-normalized.
|
|
2291
|
+
*
|
|
2292
|
+
* @category Arrangement & Analysis
|
|
2293
|
+
*/
|
|
2294
|
+
type BarPositionProfile = {
|
|
2295
|
+
/** The time signature this profile's bar is read in. */
|
|
2296
|
+
ts: TimeSignature;
|
|
2297
|
+
/** Slots in one bar of `ts`, at one twelfth of a quarter-note beat each. */
|
|
2298
|
+
slotsPerBar: number;
|
|
2299
|
+
/** Onset mass per slot, in bar order starting at the downbeat; sums to 1. */
|
|
2300
|
+
shares: number[];
|
|
2301
|
+
/** Onsets read under this signature. */
|
|
2302
|
+
onsets: number;
|
|
2303
|
+
};
|
|
2304
|
+
/**
|
|
2305
|
+
* How a line places its onsets against the meter.
|
|
2306
|
+
*
|
|
2307
|
+
* @category Arrangement & Analysis
|
|
2308
|
+
*/
|
|
2309
|
+
type RhythmAnalysis = {
|
|
2310
|
+
/** First beat of the analysed span. */
|
|
2311
|
+
startBeat: number;
|
|
2312
|
+
/** End of the analysed span, exclusive. */
|
|
2313
|
+
endBeat: number;
|
|
2314
|
+
/** The span's length in bars, counted across any meter changes it crosses. */
|
|
2315
|
+
bars: number;
|
|
2316
|
+
/** Onsets read, folding onsets within 0.05 beat of one another into one. */
|
|
2317
|
+
onsets: number;
|
|
2318
|
+
/** Onsets per bar; 0 for a span with no bars. */
|
|
2319
|
+
onsetDensity: number;
|
|
2320
|
+
/** Onsets per bar of the span, one entry per bar including a part bar at either end. */
|
|
2321
|
+
barOnsets: number[];
|
|
2322
|
+
/**
|
|
2323
|
+
* Onset mass by rhythmic level, indexed 0–5: 0 off the first pulse
|
|
2324
|
+
* subdivision, 1 on it, 2–5 on a main pulse (`metricWeight` plus 2). Sums to 1.
|
|
2325
|
+
*/
|
|
2326
|
+
onsetLevels: number[];
|
|
2327
|
+
/** Onset placement within the bar, one profile per time signature the span reads under. */
|
|
2328
|
+
barPositions: BarPositionProfile[];
|
|
2329
|
+
/** Inter-onset-interval mass, binned to {@link RHYTHM_IOI_BINS}; sums to 1. */
|
|
2330
|
+
interOnsetShares: number[];
|
|
2331
|
+
/** Share of the span during which nothing sounds. */
|
|
2332
|
+
restRatio: number;
|
|
2333
|
+
/** Longuet-Higgins & Lee syncopation, in [0, 1]. */
|
|
2334
|
+
syncopation: number;
|
|
2335
|
+
/** Share of onsets further than 1/32 beat from the nearest grid slot. */
|
|
2336
|
+
offGridRatio: number;
|
|
2337
|
+
/** Why the line reads as it does. */
|
|
2338
|
+
rationale: string;
|
|
2339
|
+
};
|
|
2340
|
+
/**
|
|
2341
|
+
* Inter-onset intervals, in quarter-note beats, at half-octave steps from a
|
|
2342
|
+
* sixteenth of a beat to sixteen beats.
|
|
2343
|
+
*
|
|
2344
|
+
* @category Arrangement & Analysis
|
|
2345
|
+
*/
|
|
2346
|
+
declare const RHYTHM_IOI_BINS: readonly number[];
|
|
2347
|
+
/**
|
|
2348
|
+
* How a line places its onsets against the meter: density, metric placement,
|
|
2349
|
+
* interval spacing, rest, and Longuet-Higgins & Lee syncopation.
|
|
2350
|
+
*
|
|
2351
|
+
* Onsets within 0.05 beat of one another read as one, and an
|
|
2352
|
+
* onset further than 1/32 beat from the nearest twelfth-of-a-beat slot is read
|
|
2353
|
+
* as off grid; every onset is moved to its nearest slot for everything
|
|
2354
|
+
* downstream of it, so an unquantized line reads a real but reduced
|
|
2355
|
+
* syncopation rather than a spurious one from a grid it never intended to sit
|
|
2356
|
+
* on.
|
|
2357
|
+
*
|
|
2358
|
+
* @param notes The line's notes, in any order. Notes that never sound
|
|
2359
|
+
* (`durationBeat <= 0`) are dropped.
|
|
2360
|
+
* @param opts Analysis options; see {@link RhythmAnalysisOptions}.
|
|
2361
|
+
* @returns The rhythm reading; see {@link RhythmAnalysis}.
|
|
2362
|
+
* @example
|
|
2363
|
+
* ```ts
|
|
2364
|
+
* import { analyzeRhythm } from '@libraz/libcantus';
|
|
2365
|
+
* const rhythm = analyzeRhythm(
|
|
2366
|
+
* [
|
|
2367
|
+
* { pitch: 60, startBeat: 0, durationBeat: 1.5 },
|
|
2368
|
+
* { pitch: 62, startBeat: 1.5, durationBeat: 2.5 },
|
|
2369
|
+
* ],
|
|
2370
|
+
* { ts: '4/4' },
|
|
2371
|
+
* );
|
|
2372
|
+
* rhythm.onsets; // 2
|
|
2373
|
+
* rhythm.syncopation > 0; // true
|
|
2374
|
+
* ```
|
|
2375
|
+
* @category Arrangement & Analysis
|
|
2376
|
+
*/
|
|
2377
|
+
declare function analyzeRhythm(notes: readonly NoteEvent[], opts?: RhythmAnalysisOptions): RhythmAnalysis;
|
|
2378
|
+
|
|
2379
|
+
/**
|
|
2380
|
+
* A structural fingerprint of a piece: form, phrase shape, harmonic function
|
|
2381
|
+
* and rhythm, and how its motifs derive from one another — everything
|
|
2382
|
+
* `compareReferences` needs to measure two pieces against each other,
|
|
2383
|
+
* dimension by dimension, without carrying the note sequence itself.
|
|
2384
|
+
*
|
|
2385
|
+
* A profile is plain data, JSON-serializable end to end: nothing in it is a
|
|
2386
|
+
* class instance or a function. `profileVersion` gates the shape this file
|
|
2387
|
+
* declares, not the analysis behind it — a schema change bumps it, a reading
|
|
2388
|
+
* that changes only because the analyzer improved does not.
|
|
2389
|
+
*/
|
|
2390
|
+
|
|
2391
|
+
/**
|
|
2392
|
+
* Schema version {@link ReferenceProfile} is written at.
|
|
2393
|
+
*
|
|
2394
|
+
* {@link assertReferenceProfile} rejects any other value outright rather than
|
|
2395
|
+
* guess at an older shape a caller's stored JSON might be in.
|
|
2396
|
+
*
|
|
2397
|
+
* @category Arrangement & Analysis
|
|
2398
|
+
*/
|
|
2399
|
+
declare const REFERENCE_PROFILE_VERSION = 1;
|
|
2400
|
+
/**
|
|
2401
|
+
* A structural fingerprint of a piece, recovered from its notes and held
|
|
2402
|
+
* without the notes themselves.
|
|
2403
|
+
*
|
|
2404
|
+
* @category Arrangement & Analysis
|
|
2405
|
+
*/
|
|
2406
|
+
type ReferenceProfile = {
|
|
2407
|
+
/** Schema version this record is written at; see {@link REFERENCE_PROFILE_VERSION}. */
|
|
2408
|
+
profileVersion: number;
|
|
2409
|
+
/** The analysed span. */
|
|
2410
|
+
span: {
|
|
2411
|
+
startBeat: number;
|
|
2412
|
+
endBeat: number;
|
|
2413
|
+
bars: number;
|
|
2414
|
+
};
|
|
2415
|
+
/** The piece's meter across the analysed span. */
|
|
2416
|
+
meters: MeterMap;
|
|
2417
|
+
/** Sections, phrases and the hypermetric grouping they sit in. */
|
|
2418
|
+
form: ReferenceForm;
|
|
2419
|
+
/** Keys, structural harmony, and harmonic rhythm. */
|
|
2420
|
+
harmony: ReferenceHarmony;
|
|
2421
|
+
/** Register, contour, motifs and their derivations, and melodic rhythm. */
|
|
2422
|
+
melody: ReferenceMelody;
|
|
2423
|
+
};
|
|
2424
|
+
/**
|
|
2425
|
+
* The formal reading of a profiled piece: its hypermetric grouping, the
|
|
2426
|
+
* sections that grouping and repetition reveal, and the phrases within them.
|
|
2427
|
+
*
|
|
2428
|
+
* @category Arrangement & Analysis
|
|
2429
|
+
*/
|
|
2430
|
+
type ReferenceForm = {
|
|
2431
|
+
/** The hyperbar grouping the phrase and section boundaries are read against. */
|
|
2432
|
+
hypermeter: {
|
|
2433
|
+
groupBars: number;
|
|
2434
|
+
confidence: number;
|
|
2435
|
+
};
|
|
2436
|
+
/** Sections, labelled by which earlier section they restate. */
|
|
2437
|
+
sections: FormSection[];
|
|
2438
|
+
/** Phrases, in time order. */
|
|
2439
|
+
phrases: ReferencePhrase[];
|
|
2440
|
+
};
|
|
2441
|
+
/**
|
|
2442
|
+
* One phrase: its span, the section it opens in, how it cadences, and the
|
|
2443
|
+
* melodic and motivic content within it.
|
|
2444
|
+
*
|
|
2445
|
+
* @category Arrangement & Analysis
|
|
2446
|
+
*/
|
|
2447
|
+
type ReferencePhrase = {
|
|
2448
|
+
/** First beat of the phrase. */
|
|
2449
|
+
startBeat: number;
|
|
2450
|
+
/** End of the phrase, exclusive. */
|
|
2451
|
+
endBeat: number;
|
|
2452
|
+
/** The phrase's length in bars. */
|
|
2453
|
+
bars: number;
|
|
2454
|
+
/** Index into `form.sections` of the section this phrase's start beat falls in. */
|
|
2455
|
+
section: number | null;
|
|
2456
|
+
/** Confidence of the phrase boundary, in [0, 1]. */
|
|
2457
|
+
confidence: number;
|
|
2458
|
+
/** The cadence the phrase ends on, or null when it closes on none. */
|
|
2459
|
+
cadence: ReferenceCadence | null;
|
|
2460
|
+
/** The phrase's melodic descriptors, or null when fewer than two notes sound within it. */
|
|
2461
|
+
melody: ReferencePhraseMelody | null;
|
|
2462
|
+
/** Indices into `melody.graph.nodes` of every motif statement that starts within this phrase. */
|
|
2463
|
+
motifNodes: number[];
|
|
2464
|
+
};
|
|
2465
|
+
/**
|
|
2466
|
+
* How a melodic line reads within one phrase.
|
|
2467
|
+
*
|
|
2468
|
+
* @category Arrangement & Analysis
|
|
2469
|
+
*/
|
|
2470
|
+
type ReferencePhraseMelody = {
|
|
2471
|
+
/** The phrase's overall shape. */
|
|
2472
|
+
shape: MelodicContourShape;
|
|
2473
|
+
/** Lowest pitch sounding in the phrase. */
|
|
2474
|
+
low: number;
|
|
2475
|
+
/** Highest pitch sounding in the phrase. */
|
|
2476
|
+
high: number;
|
|
2477
|
+
/** Duration-weighted mean pitch, truncated to the phrase's span. */
|
|
2478
|
+
mean: number;
|
|
2479
|
+
/** Pitch of the phrase's highest note (the first, when several tie). */
|
|
2480
|
+
peakPitch: number;
|
|
2481
|
+
/** Onset of the phrase's peak note, as a fraction of the phrase's length, in [0, 1]. */
|
|
2482
|
+
peakPosition: number;
|
|
2483
|
+
/**
|
|
2484
|
+
* Eight sampled points across the phrase, each the sounding pitch at that
|
|
2485
|
+
* point minus the piece's overall melodic mean, in semitones.
|
|
2486
|
+
*/
|
|
2487
|
+
outline: number[];
|
|
2488
|
+
/** Onsets per bar within the phrase; see {@link RhythmAnalysis.onsetDensity}. */
|
|
2489
|
+
onsetDensity: number;
|
|
2490
|
+
/** Share of the phrase during which nothing sounds. */
|
|
2491
|
+
restRatio: number;
|
|
2492
|
+
};
|
|
2493
|
+
/**
|
|
2494
|
+
* A cadence read at a structural boundary.
|
|
2495
|
+
*
|
|
2496
|
+
* @category Arrangement & Analysis
|
|
2497
|
+
*/
|
|
2498
|
+
type ReferenceCadence = {
|
|
2499
|
+
/** Beat the cadence arrives at. */
|
|
2500
|
+
atBeat: number;
|
|
2501
|
+
/** The cadence type. */
|
|
2502
|
+
type: CadenceType;
|
|
2503
|
+
/** How strongly the cadence closes the boundary it sits at, in [0, 1]. */
|
|
2504
|
+
weight: number;
|
|
2505
|
+
};
|
|
2506
|
+
/**
|
|
2507
|
+
* The harmonic reading of a profiled piece: its key regions, its structural
|
|
2508
|
+
* chords, and how densely those chords change.
|
|
2509
|
+
*
|
|
2510
|
+
* @category Arrangement & Analysis
|
|
2511
|
+
*/
|
|
2512
|
+
type ReferenceHarmony = {
|
|
2513
|
+
/** Key regions across the analysed span. */
|
|
2514
|
+
keys: ReferenceKeyRegion[];
|
|
2515
|
+
/** Chords reduced from the piece's harmony. */
|
|
2516
|
+
chords: ReferenceChord[];
|
|
2517
|
+
/** Onset placement of chord changes, read the way a melodic line's onsets are. */
|
|
2518
|
+
rhythm: RhythmAnalysis;
|
|
2519
|
+
};
|
|
2520
|
+
/**
|
|
2521
|
+
* One span of the piece read in a single key.
|
|
2522
|
+
*
|
|
2523
|
+
* @category Arrangement & Analysis
|
|
2524
|
+
*/
|
|
2525
|
+
type ReferenceKeyRegion = {
|
|
2526
|
+
/** First beat of the region. */
|
|
2527
|
+
startBeat: number;
|
|
2528
|
+
/** End of the region, exclusive. */
|
|
2529
|
+
endBeat: number;
|
|
2530
|
+
/** The key the region is read in. */
|
|
2531
|
+
key: ResolvedKey;
|
|
2532
|
+
/** Confidence of the key reading, in [0, 1]. */
|
|
2533
|
+
confidence: number;
|
|
2534
|
+
};
|
|
2535
|
+
/**
|
|
2536
|
+
* One reduced chord, named against the key region it falls in.
|
|
2537
|
+
*
|
|
2538
|
+
* @category Arrangement & Analysis
|
|
2539
|
+
*/
|
|
2540
|
+
type ReferenceChord = {
|
|
2541
|
+
/** First beat of the chord. */
|
|
2542
|
+
startBeat: number;
|
|
2543
|
+
/** End of the chord, exclusive. */
|
|
2544
|
+
endBeat: number;
|
|
2545
|
+
/** Index into `harmony.keys` of the region this chord is read against. */
|
|
2546
|
+
key: number;
|
|
2547
|
+
/** The chord, as a Roman numeral in the region's key. */
|
|
2548
|
+
roman: string;
|
|
2549
|
+
/** The chord's harmonic function. */
|
|
2550
|
+
function: HarmonicFunction;
|
|
2551
|
+
/** How the chord survived harmonic reduction. */
|
|
2552
|
+
level: ReductionLevel;
|
|
2553
|
+
};
|
|
2554
|
+
/**
|
|
2555
|
+
* The melodic reading of a profiled piece: register and contour, its motifs
|
|
2556
|
+
* and how they derive from one another, and its rhythm.
|
|
2557
|
+
*
|
|
2558
|
+
* @category Arrangement & Analysis
|
|
2559
|
+
*/
|
|
2560
|
+
type ReferenceMelody = {
|
|
2561
|
+
/** The melodic line's pitch range and mean, or null when no note sounds. */
|
|
2562
|
+
register: {
|
|
2563
|
+
low: number;
|
|
2564
|
+
high: number;
|
|
2565
|
+
mean: number;
|
|
2566
|
+
} | null;
|
|
2567
|
+
/** The melodic line's overall shape, or null when fewer than two notes sound. */
|
|
2568
|
+
shape: MelodicContourShape | null;
|
|
2569
|
+
/** Motifs found in the melodic line. */
|
|
2570
|
+
motifs: ReferenceMotif[];
|
|
2571
|
+
/** How the motifs' statements derive from one another. */
|
|
2572
|
+
graph: MotifGraph;
|
|
2573
|
+
/** Onset placement of the melodic line. */
|
|
2574
|
+
rhythm: RhythmAnalysis;
|
|
2575
|
+
};
|
|
2576
|
+
/**
|
|
2577
|
+
* One motif, held as the interval and rhythm ratios it repeats under
|
|
2578
|
+
* transformation rather than as the notes of any one statement.
|
|
2579
|
+
*
|
|
2580
|
+
* @category Arrangement & Analysis
|
|
2581
|
+
*/
|
|
2582
|
+
type ReferenceMotif = {
|
|
2583
|
+
/** Semitones between consecutive notes of the first statement (`MotifData.intervals`). */
|
|
2584
|
+
intervals: number[];
|
|
2585
|
+
/** Onset-to-onset ratios of the first statement (`MotifData.rhythm`), each gap over the first. */
|
|
2586
|
+
rhythm: number[];
|
|
2587
|
+
/**
|
|
2588
|
+
* Onset gap between the first two notes of the first statement, in beats:
|
|
2589
|
+
* the unit `rhythm` is measured in. 0 for a one-note motif.
|
|
2590
|
+
*/
|
|
2591
|
+
unitBeats: number;
|
|
2592
|
+
/** Length of the first statement, in beats. */
|
|
2593
|
+
spanBeats: number;
|
|
2594
|
+
/** How many statements of this motif were found. */
|
|
2595
|
+
occurrences: number;
|
|
2596
|
+
};
|
|
2597
|
+
|
|
2598
|
+
export { CADENCE_TYPES as C, HARMONIC_FUNCTIONS as H, MELODIC_CONTOUR_SHAPES as M, REDUCTION_LEVELS as R, REFERENCE_PROFILE_VERSION as S, RHYTHM_IOI_BINS as T, reduceProgression as aA, relateMotifs as aB, romanToChord as aC, secondaryDominant as aD, secondaryDominantOf as aE, sectionsFromNotes as aF, toVoiceNotes as aG, analyzeChord as ad, analyzeRhythm as ae, analyzeVoice as af, assertChordTimeline as ag, borrowedSource as ah, chordTimelineFromChords as ai, chordTimelineFromNotes as aj, chordToRoman as ak, detectCadence as al, detectCadences as am, detectModulations as an, explainRoman as ao, extractMotifs as ap, functionOf as aq, isBorrowedChord as ar, isDiatonic as as, isMinorKey as at, keyTimelineFromNotes as au, melodicContour as av, motifFromNotes as aw, motifGraph as ax, pivotChords as ay, prevailingKeyOf as az, MOTIF_RELATION_KINDS as t };
|
|
2599
|
+
export type { ReferenceHarmony as $, AnalyzeChordOptions as A, BarPositionProfile as B, DetectCadenceOptions as D, ExplainRomanOptions as E, FormSection as F, MotifGraphNode as G, IdentifiedVoiceNote as I, MotifGraphOptions as J, KeyContext as K, MotifOccurrence as L, MotifRelation as N, MotifRelationKind as O, MotifRelationSummary as P, PivotChord as Q, ReduceProgressionOptions as U, ReducedChord as V, ReductionBasis as W, ReductionLevel as X, ReferenceCadence as Y, ReferenceChord as Z, ReferenceForm as _, AnalyzedNote as a, ReferenceKeyRegion as a0, ReferenceMelody as a1, ReferenceMotif as a2, ReferencePhrase as a3, ReferencePhraseMelody as a4, ReferenceProfile as a5, RejectedCandidate as a6, RhythmAnalysis as a7, RhythmAnalysisOptions as a8, RomanExplanation as a9, SuspensionFigure as aa, TheoryLabel as ab, VoiceNote as ac, BorrowedSource as b, CadenceHit as c, CadenceResult as d, CadenceType as e, ChordAnalysis as f, ChordSegmentation as g, ChordTimeline as h, ChordTimelineOptions as i, ChordTimelineResult as j, ChordToRomanOptions as k, ContourDirection as l, ExtractMotifsOptions as m, FormSectionOptions as n, HarmonicFunction as o, KeyProfileName as p, KeyProfilePair as q, KeyRegion as r, KeyTimelineOptions as s, MelodicContour as u, MelodicContourShape as v, MelodicPhrase as w, MotifData as x, MotifGraph as y, MotifGraphEdge as z };
|