@libraz/libcantus-wasm 0.0.0-stage → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2599 @@
1
+ import { b as MeterLike, T as TimeSignature, c as MeterMap } from './index-Bf0Sv8a9.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-CUhHc3Tu.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 };