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