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