@libraz/libcantus 0.9.4 → 1.0.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.
Files changed (186) hide show
  1. package/README.md +61 -261
  2. package/README_ja.md +115 -0
  3. package/dist/analyze/index.cjs +54 -7
  4. package/dist/analyze/index.cjs.map +1 -1
  5. package/dist/analyze/index.d.cts +213 -456
  6. package/dist/analyze/index.d.ts +213 -456
  7. package/dist/analyze/index.js +56 -9
  8. package/dist/chunk-3JXCW6DX.cjs +3220 -0
  9. package/dist/chunk-3JXCW6DX.cjs.map +1 -0
  10. package/dist/chunk-4A2RMUCC.js +7647 -0
  11. package/dist/chunk-4A2RMUCC.js.map +1 -0
  12. package/dist/chunk-6XPTBE7Y.cjs +49 -0
  13. package/dist/chunk-6XPTBE7Y.cjs.map +1 -0
  14. package/dist/chunk-AFM2ULJH.cjs +5121 -0
  15. package/dist/chunk-AFM2ULJH.cjs.map +1 -0
  16. package/dist/chunk-E3F4AHAH.cjs +690 -0
  17. package/dist/chunk-E3F4AHAH.cjs.map +1 -0
  18. package/dist/chunk-ELCTZUJJ.js +379 -0
  19. package/dist/chunk-ELCTZUJJ.js.map +1 -0
  20. package/dist/chunk-FVSI36UV.js +690 -0
  21. package/dist/chunk-FVSI36UV.js.map +1 -0
  22. package/dist/chunk-GEDTJHAC.cjs +1 -0
  23. package/dist/chunk-GEDTJHAC.cjs.map +1 -0
  24. package/dist/chunk-GOZG57ER.js +3220 -0
  25. package/dist/chunk-GOZG57ER.js.map +1 -0
  26. package/dist/chunk-H3VORETI.js +2243 -0
  27. package/dist/chunk-H3VORETI.js.map +1 -0
  28. package/dist/chunk-H42UHPYW.js +1577 -0
  29. package/dist/chunk-H42UHPYW.js.map +1 -0
  30. package/dist/chunk-HFPS7JFD.js +1 -0
  31. package/dist/chunk-INHVXP6Z.js +3053 -0
  32. package/dist/chunk-INHVXP6Z.js.map +1 -0
  33. package/dist/chunk-K4ZJUGF4.cjs +379 -0
  34. package/dist/chunk-K4ZJUGF4.cjs.map +1 -0
  35. package/dist/chunk-KNJEKLKV.js +49 -0
  36. package/dist/chunk-KNJEKLKV.js.map +1 -0
  37. package/dist/chunk-M4CWTJWJ.cjs +7647 -0
  38. package/dist/chunk-M4CWTJWJ.cjs.map +1 -0
  39. package/dist/chunk-MXO72PLY.cjs +211 -0
  40. package/dist/chunk-MXO72PLY.cjs.map +1 -0
  41. package/dist/chunk-NLEU4QSE.cjs +360 -0
  42. package/dist/chunk-NLEU4QSE.cjs.map +1 -0
  43. package/dist/chunk-OE6WK2Y2.cjs +1577 -0
  44. package/dist/chunk-OE6WK2Y2.cjs.map +1 -0
  45. package/dist/chunk-Q2WGKJNN.cjs +1064 -0
  46. package/dist/chunk-Q2WGKJNN.cjs.map +1 -0
  47. package/dist/chunk-QYQQ5J6E.js +1 -0
  48. package/dist/chunk-QYQQ5J6E.js.map +1 -0
  49. package/dist/chunk-RHIJ3S4I.cjs +1 -0
  50. package/dist/chunk-RHIJ3S4I.cjs.map +1 -0
  51. package/dist/chunk-TTCLJX6D.js +211 -0
  52. package/dist/chunk-TTCLJX6D.js.map +1 -0
  53. package/dist/chunk-UADYAYAT.cjs +3053 -0
  54. package/dist/chunk-UADYAYAT.cjs.map +1 -0
  55. package/dist/chunk-VOHZB45S.js +5121 -0
  56. package/dist/chunk-VOHZB45S.js.map +1 -0
  57. package/dist/chunk-VTI6FOLB.js +1064 -0
  58. package/dist/chunk-VTI6FOLB.js.map +1 -0
  59. package/dist/chunk-WWURE4XT.cjs +2243 -0
  60. package/dist/chunk-WWURE4XT.cjs.map +1 -0
  61. package/dist/chunk-YH3BIKHH.js +360 -0
  62. package/dist/chunk-YH3BIKHH.js.map +1 -0
  63. package/dist/core/index.cjs +103 -6
  64. package/dist/core/index.cjs.map +1 -1
  65. package/dist/core/index.d.cts +96 -345
  66. package/dist/core/index.d.ts +96 -345
  67. package/dist/core/index.js +104 -7
  68. package/dist/generate/index.cjs +89 -10
  69. package/dist/generate/index.cjs.map +1 -1
  70. package/dist/generate/index.d.cts +437 -1095
  71. package/dist/generate/index.d.ts +437 -1095
  72. package/dist/generate/index.js +94 -15
  73. package/dist/index-9wcMhG73.d.ts +1095 -0
  74. package/dist/{index-D6b6na69.d.cts → index-B4o55NDr.d.cts} +13 -9
  75. package/dist/index-B9MNZboQ.d.cts +770 -0
  76. package/dist/index-B9MNZboQ.d.ts +770 -0
  77. package/dist/index-BGFW-8P2.d.cts +2307 -0
  78. package/dist/index-BO6xE9YU.d.cts +1804 -0
  79. package/dist/index-BkGmlyI3.d.cts +470 -0
  80. package/dist/index-CCNJRG-P.d.cts +1095 -0
  81. package/dist/index-CGpRv5sl.d.cts +643 -0
  82. package/dist/index-C_8o--VE.d.cts +1242 -0
  83. package/dist/index-CgHqxdps.d.ts +2307 -0
  84. package/dist/index-Chbst3Jx.d.ts +1343 -0
  85. package/dist/index-Cj49F892.d.ts +470 -0
  86. package/dist/{index-tSQh-xwY.d.ts → index-CunYKLiu.d.ts} +13 -9
  87. package/dist/index-D57QRbVn.d.ts +1804 -0
  88. package/dist/index-DInQqT8Q.d.cts +66 -0
  89. package/dist/index-DInQqT8Q.d.ts +66 -0
  90. package/dist/index-Dzr13q3d.d.cts +1343 -0
  91. package/dist/index-G1uwGGWQ.d.ts +643 -0
  92. package/dist/index-szBv3496.d.ts +1242 -0
  93. package/dist/index.cjs +358 -15
  94. package/dist/index.cjs.map +1 -1
  95. package/dist/index.d.cts +17 -15
  96. package/dist/index.d.ts +17 -15
  97. package/dist/index.js +407 -64
  98. package/dist/masks-DYbE485J.d.cts +445 -0
  99. package/dist/masks-DYbE485J.d.ts +445 -0
  100. package/dist/model/index.cjs +39 -7
  101. package/dist/model/index.cjs.map +1 -1
  102. package/dist/model/index.d.cts +4685 -243
  103. package/dist/model/index.d.ts +4685 -243
  104. package/dist/model/index.js +40 -8
  105. package/dist/positional-Cptlj-xs.d.ts +287 -0
  106. package/dist/positional-DvH_sd8u.d.cts +287 -0
  107. package/dist/theory/index.cjs +101 -7
  108. package/dist/theory/index.cjs.map +1 -1
  109. package/dist/theory/index.d.cts +513 -173
  110. package/dist/theory/index.d.ts +513 -173
  111. package/dist/theory/index.js +118 -24
  112. package/package.json +16 -11
  113. package/dist/chunk-36N73KZ3.cjs +0 -246
  114. package/dist/chunk-36N73KZ3.cjs.map +0 -1
  115. package/dist/chunk-4HLLZPXT.cjs +0 -3077
  116. package/dist/chunk-4HLLZPXT.cjs.map +0 -1
  117. package/dist/chunk-7MGZ7D62.cjs +0 -498
  118. package/dist/chunk-7MGZ7D62.cjs.map +0 -1
  119. package/dist/chunk-7NKDPF74.js +0 -3077
  120. package/dist/chunk-7NKDPF74.js.map +0 -1
  121. package/dist/chunk-CAN76NCU.cjs +0 -679
  122. package/dist/chunk-CAN76NCU.cjs.map +0 -1
  123. package/dist/chunk-D2FAJBYL.js +0 -479
  124. package/dist/chunk-D2FAJBYL.js.map +0 -1
  125. package/dist/chunk-EHVEBWM5.js +0 -1449
  126. package/dist/chunk-EHVEBWM5.js.map +0 -1
  127. package/dist/chunk-FCANXBAT.cjs +0 -30
  128. package/dist/chunk-FCANXBAT.cjs.map +0 -1
  129. package/dist/chunk-FNDWXRRI.cjs +0 -479
  130. package/dist/chunk-FNDWXRRI.cjs.map +0 -1
  131. package/dist/chunk-GQSGS2N4.js +0 -173
  132. package/dist/chunk-GQSGS2N4.js.map +0 -1
  133. package/dist/chunk-HKGYCQ34.js +0 -53
  134. package/dist/chunk-HKGYCQ34.js.map +0 -1
  135. package/dist/chunk-I24MV65U.js +0 -106
  136. package/dist/chunk-I24MV65U.js.map +0 -1
  137. package/dist/chunk-KMHOICIY.js +0 -679
  138. package/dist/chunk-KMHOICIY.js.map +0 -1
  139. package/dist/chunk-LW53AHQU.cjs +0 -1117
  140. package/dist/chunk-LW53AHQU.cjs.map +0 -1
  141. package/dist/chunk-N6IHQUOX.js +0 -1
  142. package/dist/chunk-NKIBQ6PT.js +0 -30
  143. package/dist/chunk-NKIBQ6PT.js.map +0 -1
  144. package/dist/chunk-NP4NA2FB.cjs +0 -106
  145. package/dist/chunk-NP4NA2FB.cjs.map +0 -1
  146. package/dist/chunk-NVE34YGZ.cjs +0 -1449
  147. package/dist/chunk-NVE34YGZ.cjs.map +0 -1
  148. package/dist/chunk-NYYWMV2C.js +0 -327
  149. package/dist/chunk-NYYWMV2C.js.map +0 -1
  150. package/dist/chunk-Q2XUP227.js +0 -845
  151. package/dist/chunk-Q2XUP227.js.map +0 -1
  152. package/dist/chunk-Q6OP4U43.cjs +0 -327
  153. package/dist/chunk-Q6OP4U43.cjs.map +0 -1
  154. package/dist/chunk-RC6GBMCD.cjs +0 -845
  155. package/dist/chunk-RC6GBMCD.cjs.map +0 -1
  156. package/dist/chunk-RK35RIN7.js +0 -1117
  157. package/dist/chunk-RK35RIN7.js.map +0 -1
  158. package/dist/chunk-RUMU3UA6.cjs +0 -53
  159. package/dist/chunk-RUMU3UA6.cjs.map +0 -1
  160. package/dist/chunk-T64C7ZD7.cjs +0 -1
  161. package/dist/chunk-T64C7ZD7.cjs.map +0 -1
  162. package/dist/chunk-XEBG3G53.js +0 -498
  163. package/dist/chunk-XEBG3G53.js.map +0 -1
  164. package/dist/chunk-YLEMGEFH.js +0 -246
  165. package/dist/chunk-YLEMGEFH.js.map +0 -1
  166. package/dist/chunk-ZEJR4TKL.cjs +0 -173
  167. package/dist/chunk-ZEJR4TKL.cjs.map +0 -1
  168. package/dist/function-BtiZb9i9.d.ts +0 -208
  169. package/dist/function-DNugAOrt.d.cts +0 -208
  170. package/dist/index-6VR8-kit.d.ts +0 -143
  171. package/dist/index-70p168VM.d.ts +0 -192
  172. package/dist/index-Be74mcon.d.cts +0 -152
  173. package/dist/index-BtXT6UQ0.d.cts +0 -192
  174. package/dist/index-C5UBbQ4G.d.ts +0 -152
  175. package/dist/index-C83mZI1P.d.ts +0 -242
  176. package/dist/index-DXd9JikN.d.cts +0 -246
  177. package/dist/index-DXd9JikN.d.ts +0 -246
  178. package/dist/index-OG65ocOr.d.cts +0 -272
  179. package/dist/index-OG65ocOr.d.ts +0 -272
  180. package/dist/index-tJhkmQgE.d.cts +0 -143
  181. package/dist/index-y_ak9_Hi.d.cts +0 -242
  182. package/dist/styled-DIRkk9Uz.d.ts +0 -506
  183. package/dist/styled-DJbkJQfj.d.cts +0 -506
  184. package/dist/types-BN6_Q9Kl.d.cts +0 -39
  185. package/dist/types-BN6_Q9Kl.d.ts +0 -39
  186. /package/dist/{chunk-N6IHQUOX.js.map → chunk-HFPS7JFD.js.map} +0 -0
@@ -1,1449 +0,0 @@
1
- import {
2
- negativeHarmonyMirror
3
- } from "./chunk-GQSGS2N4.js";
4
- import {
5
- analyzeChord,
6
- borrowedSource,
7
- chordToRoman,
8
- detectCadence,
9
- detectChord,
10
- detectChordBest,
11
- detectKey,
12
- detectKeyBest,
13
- functionOf,
14
- isBorrowedChord,
15
- isMinorKey,
16
- romanToChord
17
- } from "./chunk-KMHOICIY.js";
18
- import {
19
- availableTensions,
20
- avoidNotes,
21
- chordScales,
22
- formatChordSymbol,
23
- parseChordSymbol,
24
- spellChord,
25
- spellChordFromRoot,
26
- spellPitchClass,
27
- spellScale,
28
- voiceChord,
29
- voiceChordStyled,
30
- voiceProgression
31
- } from "./chunk-RK35RIN7.js";
32
- import {
33
- chordFromDegree,
34
- chordPitchClasses,
35
- diatonicSeventh,
36
- diatonicTriad,
37
- isScaleTone,
38
- majorKey,
39
- makeChord,
40
- minorKey,
41
- scaleByName,
42
- scaleTonesInDegreeOrder,
43
- transposeChord
44
- } from "./chunk-D2FAJBYL.js";
45
- import {
46
- InvalidInputError,
47
- assertFiniteNumber,
48
- formatNote,
49
- intervalSemitones,
50
- isConsonantInterval,
51
- midiToNote,
52
- noteToMidi,
53
- noteToPitchClass,
54
- parseInterval,
55
- parseNote,
56
- pitchClassOf,
57
- spelledInterval,
58
- transposeByInterval,
59
- transposeNote
60
- } from "./chunk-XEBG3G53.js";
61
-
62
- // src/model/interval.ts
63
- var INVERSION_SUM = 9;
64
- function invertQuality(quality) {
65
- if (quality === "P") {
66
- return "P";
67
- }
68
- if (quality === "M") {
69
- return "m";
70
- }
71
- if (quality === "m") {
72
- return "M";
73
- }
74
- return quality.startsWith("A") ? `d${"d".repeat(quality.length - 1)}` : `A${"A".repeat(quality.length - 1)}`;
75
- }
76
- var Interval = class _Interval {
77
- #number;
78
- #quality;
79
- #semitones;
80
- constructor(numberValue, quality, semitones) {
81
- this.#number = numberValue;
82
- this.#quality = quality;
83
- this.#semitones = semitones;
84
- }
85
- /**
86
- * The spelled interval between two notes.
87
- *
88
- * @param a The first note.
89
- * @param b The second note.
90
- * @returns The interval from `a` to `b`.
91
- */
92
- static between(a, b) {
93
- return a.intervalTo(b);
94
- }
95
- /**
96
- * Build an interval from explicit components.
97
- *
98
- * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
99
- * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
100
- * @param semitones Signed semitone span; its magnitude must be the span the
101
- * number and quality describe.
102
- * @returns The interval.
103
- * @throws If the three components do not describe the same interval — a
104
- * `P5` spanning 8 semitones is not a value any other method can produce.
105
- */
106
- static of(numberValue, quality, semitones) {
107
- const expected = intervalSemitones(numberValue, quality);
108
- if (Math.abs(semitones) !== expected) {
109
- throw new InvalidInputError(
110
- `${quality}${numberValue} spans ${expected} semitones; received ${semitones}`
111
- );
112
- }
113
- return new _Interval(numberValue, quality, semitones);
114
- }
115
- /**
116
- * Wrap a plain spelled interval, as returned by the pitch module.
117
- *
118
- * @param data The plain interval.
119
- * @returns The wrapped interval.
120
- */
121
- static fromData(data) {
122
- return new _Interval(data.number, data.quality, data.semitones);
123
- }
124
- /**
125
- * Rebuild an interval from its {@link Interval.toJSON} output.
126
- *
127
- * @param data The serialized interval.
128
- * @returns The wrapped interval.
129
- */
130
- static fromJSON(data) {
131
- return _Interval.fromData(data);
132
- }
133
- /**
134
- * Parse an interval name such as `'P5'`, `'m3'`, or `'AA4'`.
135
- *
136
- * @param name The interval name.
137
- * @returns The ascending interval of that name.
138
- * @throws If the name is not a quality label followed by a diatonic number.
139
- */
140
- static parse(name) {
141
- return _Interval.fromData(parseInterval(name));
142
- }
143
- /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
144
- get number() {
145
- return this.#number;
146
- }
147
- /** Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`. */
148
- get quality() {
149
- return this.#quality;
150
- }
151
- /** Signed semitone span. */
152
- get semitones() {
153
- return this.#semitones;
154
- }
155
- /** A readable label composed of quality and number, e.g. `'P5'` or `'M3'`. */
156
- get name() {
157
- return `${this.#quality}${this.#number}`;
158
- }
159
- /**
160
- * The interval's inversion: the complement that completes the octave.
161
- *
162
- * A compound interval is reduced to its simple form first, and the result is
163
- * always ascending — an inversion answers "what is left of the octave",
164
- * which has no direction of its own.
165
- *
166
- * @returns The inverted interval, e.g. `M3` becomes `m6`.
167
- */
168
- invert() {
169
- const simple = (this.#number - 1) % 7 + 1;
170
- const numberValue = INVERSION_SUM - simple;
171
- const quality = invertQuality(this.#quality);
172
- return _Interval.of(numberValue, quality, intervalSemitones(numberValue, quality));
173
- }
174
- /**
175
- * Whether the interval is consonant.
176
- *
177
- * @param twoVoice When true, the perfect fourth counts as a dissonance,
178
- * matching two-voice counterpoint.
179
- * @returns True if the interval is consonant in that context.
180
- */
181
- isConsonant(twoVoice = true) {
182
- return isConsonantInterval(this.#semitones, twoVoice);
183
- }
184
- /**
185
- * Whether another interval is spelled identically.
186
- *
187
- * Enharmonic equivalents are not equal: an augmented second and a minor
188
- * third span the same distance but are different intervals.
189
- *
190
- * @param other The interval to compare with.
191
- * @returns True when number, quality, and span all match.
192
- */
193
- equals(other) {
194
- return this.#number === other.number && this.#quality === other.quality && this.#semitones === other.semitones;
195
- }
196
- /**
197
- * The plain interval data, for JSON serialization.
198
- *
199
- * Private class fields do not serialize, so an explicit `toJSON` keeps
200
- * `JSON.stringify(interval)` from collapsing to `{}`.
201
- *
202
- * @returns The diatonic number, quality, and semitone span.
203
- */
204
- toJSON() {
205
- return { number: this.#number, quality: this.#quality, semitones: this.#semitones };
206
- }
207
- /**
208
- * The interval's name, so a template literal or a log line reads as the
209
- * interval.
210
- *
211
- * @returns The name, e.g. `'M3'`.
212
- */
213
- toString() {
214
- return this.name;
215
- }
216
- };
217
-
218
- // src/model/note.ts
219
- function copyNote(data) {
220
- if (!Number.isInteger(data.letter) || data.letter < 0 || data.letter > 6) {
221
- throw new InvalidInputError(
222
- `note letter must be an integer in [0, 6]; received ${data.letter}`
223
- );
224
- }
225
- const copy = { letter: data.letter, alter: data.alter };
226
- if (data.octave !== void 0) {
227
- copy.octave = data.octave;
228
- }
229
- return copy;
230
- }
231
- var Note = class _Note {
232
- #data;
233
- /**
234
- * Wrap a plain note object.
235
- *
236
- * @param data The spelled note; it is copied, never retained or mutated.
237
- * @throws If `letter` is not an integer in 0..6.
238
- */
239
- constructor(data) {
240
- this.#data = copyNote(data);
241
- }
242
- /**
243
- * Parse scientific pitch notation (e.g. `'C#4'`, `'Bb'`, `'F##3'`).
244
- *
245
- * @param name The note text.
246
- * @returns The parsed note.
247
- * @throws If the text is not a valid note.
248
- */
249
- static of(name) {
250
- return new _Note(parseNote(name));
251
- }
252
- /**
253
- * Name a MIDI number (middle C = C4 = 60) as a note.
254
- *
255
- * @param midi The MIDI number.
256
- * @param spelling Whether to prefer sharps or flats for black keys.
257
- * @returns The spelled note, with octave.
258
- */
259
- static fromMidi(midi, spelling = "sharp") {
260
- return new _Note(midiToNote(midi, spelling));
261
- }
262
- /**
263
- * Wrap an existing plain note object.
264
- *
265
- * @param data The plain note.
266
- * @returns The wrapped note.
267
- * @throws If `letter` is not an integer in 0..6.
268
- */
269
- static fromData(data) {
270
- return new _Note(data);
271
- }
272
- /** The note rendered as scientific pitch notation, e.g. `'G4'` or `'Bb'`. */
273
- get name() {
274
- return formatNote(this.#data);
275
- }
276
- /** The pitch class (0..11), ignoring octave. */
277
- get pitchClass() {
278
- return noteToPitchClass(this.#data);
279
- }
280
- /**
281
- * The MIDI number (middle C = C4 = 60).
282
- *
283
- * @throws If the note has no octave and therefore no fixed pitch.
284
- */
285
- get midi() {
286
- if (this.#data.octave === void 0) {
287
- throw new InvalidInputError(`note ${this.name} has no octave, so it has no MIDI number`);
288
- }
289
- return noteToMidi(this.#data);
290
- }
291
- /** The diatonic letter number: 0..6 for C..B. */
292
- get letter() {
293
- return this.#data.letter;
294
- }
295
- /** The chromatic alteration in semitones: -1 flat, 0 natural, +1 sharp, ... */
296
- get alter() {
297
- return this.#data.alter;
298
- }
299
- /** The octave (scientific pitch notation), or undefined for a bare pitch class. */
300
- get octave() {
301
- return this.#data.octave;
302
- }
303
- /** A copy of the underlying plain note object. */
304
- get data() {
305
- return copyNote(this.#data);
306
- }
307
- /**
308
- * Transpose by a signed number of semitones, keeping the spelling.
309
- *
310
- * The letter moves by the diatonic distance of the conventional interval for
311
- * that many semitones, so `Ab4` up a major second is `Bb4` rather than `A#4`
312
- * and a flat key stays on the flat side. An octave-less note stays
313
- * octave-less: only its pitch class is moved. Transposing by zero is the
314
- * identity: the original spelling is preserved (no enharmonic respelling).
315
- *
316
- * @param semitones The signed semitone offset.
317
- * @param opts `spelling` forces the result onto the sharp or flat side
318
- * instead of following this note's letter.
319
- * @returns The transposed note.
320
- * @example
321
- * ```ts
322
- * import { Note } from '@libraz/libcantus';
323
- * Note.of('Ab4').transpose(2).name; // 'Bb4'
324
- * Note.of('Ab4').transpose(2, { spelling: 'sharp' }).name; // 'A#4'
325
- * ```
326
- */
327
- transpose(semitones, opts) {
328
- if (semitones === 0 && opts?.spelling === void 0) {
329
- return new _Note(this.#data);
330
- }
331
- return new _Note(transposeNote(this.#data, semitones, opts));
332
- }
333
- /**
334
- * The spelled interval from this note to another.
335
- *
336
- * @param other The second note.
337
- * @returns The interval, which {@link Interval.toJSON} unwraps to plain data.
338
- */
339
- intervalTo(other) {
340
- return Interval.fromData(spelledInterval(this.#data, other.data));
341
- }
342
- /**
343
- * Transpose by a spelled interval, keeping the spelling the interval names.
344
- *
345
- * Unlike {@link Note.transpose}, which picks a letter from the semitone
346
- * count, the interval's diatonic number decides the letter: C up an
347
- * augmented second is D#, not Eb.
348
- *
349
- * @param interval The interval to apply; a descending interval moves down.
350
- * @returns The transposed note.
351
- * @example
352
- * ```ts
353
- * import { Interval, Note } from '@libraz/libcantus';
354
- * Note.of('C4').transposeBy(Interval.parse('A2')).name; // 'D#4'
355
- * ```
356
- */
357
- transposeBy(interval) {
358
- return new _Note(transposeByInterval(this.#data, interval.toJSON()));
359
- }
360
- /**
361
- * Rebuild a note from its {@link Note.toJSON} output.
362
- *
363
- * @param data The serialized note.
364
- * @returns The wrapped note.
365
- * @throws If `letter` is not an integer in 0..6.
366
- */
367
- static fromJSON(data) {
368
- return new _Note(data);
369
- }
370
- /**
371
- * Whether another note has the same letter, alteration, and octave.
372
- *
373
- * @param other The note to compare.
374
- * @returns True if the spellings are identical.
375
- */
376
- equals(other) {
377
- const b = other.data;
378
- return this.#data.letter === b.letter && this.#data.alter === b.alter && this.#data.octave === b.octave;
379
- }
380
- /**
381
- * The plain note data, for JSON serialization.
382
- *
383
- * Private class fields do not serialize, so an explicit `toJSON` keeps
384
- * `JSON.stringify(note)` from collapsing to `{}`.
385
- *
386
- * @returns A copy of the underlying plain note object.
387
- */
388
- toJSON() {
389
- return this.data;
390
- }
391
- /**
392
- * The note's name, so a template literal or a log line reads as the note.
393
- *
394
- * @returns The spelled name, e.g. `'Bb3'`.
395
- */
396
- toString() {
397
- return this.name;
398
- }
399
- };
400
-
401
- // src/model/shared.ts
402
- function spellPitchClassBare(pc, spelling) {
403
- const spelled = midiToNote(60 + pitchClassOf(pc), spelling);
404
- return { letter: spelled.letter, alter: spelled.alter };
405
- }
406
-
407
- // src/model/key.ts
408
- function accidentalLoad(tonic, scale) {
409
- return spellScale(tonic, scale).reduce((sum, note) => sum + Math.abs(note.alter), 0);
410
- }
411
- function bestTonicForScale(rootPc, scale) {
412
- const sharp = spellPitchClassBare(rootPc, "sharp");
413
- const flat = spellPitchClassBare(rootPc, "flat");
414
- if (sharp.letter === flat.letter && sharp.alter === flat.alter) {
415
- return new Note(sharp);
416
- }
417
- return accidentalLoad(flat, scale) <= accidentalLoad(sharp, scale) ? new Note(flat) : new Note(sharp);
418
- }
419
- var Key = class _Key {
420
- #scale;
421
- #tonic;
422
- /**
423
- * Wrap a key/scale and its spelled tonic.
424
- *
425
- * @param scale The key/scale; its root is normalized to a pitch class.
426
- * @param tonic The spelled tonic anchoring letter-name spelling.
427
- */
428
- constructor(scale, tonic) {
429
- const rootPc = pitchClassOf(scale.rootPc);
430
- if (tonic.pitchClass !== rootPc) {
431
- throw new InvalidInputError(
432
- `tonic ${tonic.name} does not match the scale root pitch class ${rootPc}; pass a tonic that spells the scale root, or omit it to have one chosen`
433
- );
434
- }
435
- this.#scale = { rootPc, modeMask12: scale.modeMask12 };
436
- this.#tonic = tonic;
437
- }
438
- /**
439
- * A major key.
440
- *
441
- * @param root Tonic as a note name (e.g. `'Eb'`) or a pitch class; a numeric
442
- * root is spelled with whichever accidental side yields the fewest
443
- * accidentals across the scale.
444
- * @returns The major key.
445
- */
446
- static major(root) {
447
- if (typeof root === "string") {
448
- const tonic = Note.of(root);
449
- return new _Key(majorKey(tonic.pitchClass), tonic);
450
- }
451
- const scale = majorKey(root);
452
- return new _Key(scale, bestTonicForScale(root, scale));
453
- }
454
- /**
455
- * A natural-minor key.
456
- *
457
- * @param root Tonic as a note name or a pitch class; a numeric root is
458
- * spelled with whichever accidental side yields the fewest accidentals
459
- * across the scale.
460
- * @returns The minor key.
461
- */
462
- static minor(root) {
463
- if (typeof root === "string") {
464
- const tonic = Note.of(root);
465
- return new _Key(minorKey(tonic.pitchClass), tonic);
466
- }
467
- const scale = minorKey(root);
468
- return new _Key(scale, bestTonicForScale(root, scale));
469
- }
470
- /**
471
- * A key on a named scale (e.g. `'dorian'`, `'harmonicMinor'`).
472
- *
473
- * @param name The scale name, a key of the scale module's named-scale table.
474
- * @param root Tonic as a note name or a pitch class; a numeric root is
475
- * spelled with whichever accidental side yields the fewest accidentals
476
- * across the scale, exactly as {@link Key.major} does.
477
- * @returns The key.
478
- * @throws If the name is not a known scale.
479
- */
480
- static named(name, root) {
481
- if (typeof root === "string") {
482
- const tonic = Note.of(root);
483
- return new _Key(scaleByName(name, tonic.pitchClass), tonic);
484
- }
485
- const scale = scaleByName(name, pitchClassOf(root));
486
- return new _Key(scale, bestTonicForScale(pitchClassOf(root), scale));
487
- }
488
- /**
489
- * Wrap an existing `KeyScale`, synthesizing a spelled tonic when none is
490
- * given.
491
- *
492
- * The synthesized tonic is chosen the same way as for a numeric root
493
- * elsewhere: whichever accidental side spells the scale with the fewest
494
- * accidentals. This is what keeps `Key.of(detectKey(...).scale)` from handing
495
- * every downstream chord a double-sharp spelling.
496
- *
497
- * @param scale The key/scale to wrap.
498
- * @param tonic Optional spelled tonic; must spell the scale's root pitch class.
499
- * @returns The key.
500
- * @throws If the given tonic is not the scale's root pitch class.
501
- */
502
- static of(scale, tonic) {
503
- return new _Key(scale, tonic ?? bestTonicForScale(pitchClassOf(scale.rootPc), scale));
504
- }
505
- /**
506
- * Rebuild a key from its {@link Key.toJSON} output.
507
- *
508
- * @param data The serialized key and tonic.
509
- * @returns The key.
510
- */
511
- static fromJSON(data) {
512
- return new _Key(data.scale, new Note(data.tonic));
513
- }
514
- /**
515
- * Identify the keys a set of pitches fits, best interpretation first.
516
- *
517
- * The counterpart of {@link Chord.detect}.
518
- *
519
- * @param pitches MIDI pitches or bare pitch classes.
520
- * @param opts How to weigh the input; see {@link DetectKeyOptions}.
521
- * @returns Ranked keys (may be empty).
522
- */
523
- static detect(pitches, opts) {
524
- return detectKey(pitches, opts).map((match) => _Key.of(match.key));
525
- }
526
- /**
527
- * The single best key interpretation of a pitch set.
528
- *
529
- * @param pitches MIDI pitches or bare pitch classes.
530
- * @param opts How to weigh the input; see {@link DetectKeyOptions}.
531
- * @returns The top-ranked key, or null when nothing matches.
532
- * @example
533
- * ```ts
534
- * import { Key } from '@libraz/libcantus';
535
- * Key.detectBest([0, 2, 4, 5, 7, 9, 11])?.toString(); // 'C major'
536
- * ```
537
- */
538
- static detectBest(pitches, opts) {
539
- const best = detectKeyBest(pitches, opts);
540
- return best === null ? null : _Key.of(best.key);
541
- }
542
- /**
543
- * Whether another key has the same tonic pitch class and mode.
544
- *
545
- * The spelled tonic is not compared: C# major and Db major are the same key
546
- * written two ways.
547
- *
548
- * @param other The key to compare.
549
- * @returns True when tonic and mode mask both match.
550
- */
551
- equals(other) {
552
- const scale = other.scale;
553
- return this.#scale.rootPc === scale.rootPc && this.#scale.modeMask12 === scale.modeMask12;
554
- }
555
- /** A copy of the underlying plain `KeyScale`. */
556
- get scale() {
557
- return { rootPc: this.#scale.rootPc, modeMask12: this.#scale.modeMask12 };
558
- }
559
- /** The spelled tonic. */
560
- get tonic() {
561
- return this.#tonic;
562
- }
563
- /** The tonic pitch class (0..11). */
564
- get rootPc() {
565
- return this.#scale.rootPc;
566
- }
567
- /** Whether the scale has a minor third and no major third. */
568
- get isMinor() {
569
- return isMinorKey(this.#scale);
570
- }
571
- /**
572
- * The scale's pitch classes in ascending scale-degree order (degree 0 first).
573
- *
574
- * @returns One pitch class per scale degree.
575
- */
576
- pitchClasses() {
577
- return scaleTonesInDegreeOrder(this.#scale);
578
- }
579
- /**
580
- * Transpose the key by a number of semitones.
581
- *
582
- * The mode mask is unchanged, so the scale keeps its shape; only the tonic
583
- * moves. The new tonic is spelled the way that key is conventionally written
584
- * — D major, not C## major.
585
- *
586
- * @param semitones The signed semitone offset.
587
- * @returns The transposed key.
588
- * @example
589
- * ```ts
590
- * import { Key } from '@libraz/libcantus';
591
- * Key.major('C').transpose(2).toString(); // 'D major'
592
- * ```
593
- */
594
- transpose(semitones) {
595
- assertFiniteNumber(semitones, "semitones");
596
- const rootPc = pitchClassOf(this.#scale.rootPc + Math.round(semitones));
597
- return _Key.of({ rootPc, modeMask12: this.#scale.modeMask12 });
598
- }
599
- /**
600
- * The spelled scale, one note per degree (e.g. C D E F G A B for C major).
601
- *
602
- * @returns Spelled octave-less notes in scale-degree order.
603
- */
604
- notes() {
605
- return spellScale(this.#tonic.data, this.#scale).map((note) => new Note(note));
606
- }
607
- /**
608
- * Alias of {@link Key.notes}.
609
- *
610
- * @returns Spelled octave-less notes in scale-degree order.
611
- */
612
- spell() {
613
- return this.notes();
614
- }
615
- /**
616
- * The spelled scale as letter-name strings.
617
- *
618
- * @returns One name per scale degree.
619
- */
620
- noteNames() {
621
- return this.notes().map((note) => note.name);
622
- }
623
- /**
624
- * Build a chord on a scale degree, carrying this key as context.
625
- *
626
- * With an explicit quality the quality's interval template is attached to the
627
- * degree's diatonic root; without one the scale-correct diatonic triad is
628
- * stacked (e.g. a diminished triad on the leading tone of a major key).
629
- *
630
- * @param degree 0-based scale degree of the chord root.
631
- * @param quality Optional chord quality.
632
- * @returns The chord, with this key attached.
633
- * @throws Without a `quality`, if this key's scale is not heptatonic —
634
- * stacking thirds needs seven degrees, so the pentatonic, blues,
635
- * whole-tone, octatonic and chromatic scales have no diatonic triad. Pass
636
- * an explicit `quality` for those.
637
- */
638
- chord(degree, quality) {
639
- const data = quality === void 0 ? diatonicTriad(degree, this.#scale) : chordFromDegree(degree, quality, this.#scale);
640
- return new Chord(data, this);
641
- }
642
- /**
643
- * The diatonic triad on a scale degree, carrying this key as context.
644
- *
645
- * @param degree 0-based scale degree of the chord root.
646
- * @returns The triad, with this key attached.
647
- * @throws If this key's scale is not heptatonic; stacking thirds needs seven
648
- * degrees. Use {@link Key.chord} with an explicit quality instead.
649
- */
650
- diatonicTriad(degree) {
651
- return new Chord(diatonicTriad(degree, this.#scale), this);
652
- }
653
- /**
654
- * The diatonic seventh chord on a scale degree, carrying this key as context.
655
- *
656
- * @param degree 0-based scale degree of the chord root.
657
- * @returns The seventh chord, with this key attached.
658
- * @throws If this key's scale is not heptatonic; stacking thirds needs seven
659
- * degrees. Use {@link Key.chord} with an explicit quality instead.
660
- */
661
- diatonicSeventh(degree) {
662
- return new Chord(diatonicSeventh(degree, this.#scale), this);
663
- }
664
- /**
665
- * Build the chord denoted by a Roman numeral in this key (including applied
666
- * chords such as `'V7/V'`), carrying this key as context.
667
- *
668
- * @param text The Roman numeral.
669
- * @returns The chord, with this key attached.
670
- * @throws If the numeral is not valid.
671
- */
672
- roman(text) {
673
- return new Chord(romanToChord(text, this.#scale), this);
674
- }
675
- /**
676
- * Whether a pitch belongs to the scale.
677
- *
678
- * @param x A MIDI pitch, bare pitch class, or note.
679
- * @returns True if the pitch class is a scale tone.
680
- */
681
- contains(x) {
682
- return isScaleTone(typeof x === "number" ? x : x.pitchClass, this.#scale);
683
- }
684
- /**
685
- * The plain key data, for JSON serialization.
686
- *
687
- * Private class fields do not serialize, so an explicit `toJSON` keeps
688
- * `JSON.stringify(key)` from collapsing to `{}`. The result pairs the
689
- * `KeyScale` with the spelled tonic, enough to reconstruct the key via
690
- * {@link Key.of}.
691
- *
692
- * @returns The key/scale and its spelled tonic.
693
- */
694
- toJSON() {
695
- return { scale: this.scale, tonic: this.#tonic.data };
696
- }
697
- /**
698
- * The key's tonic and mode, so a template literal or a log line reads as the
699
- * key. Only the major/minor distinction is named, since a mask does not carry
700
- * a scale name.
701
- *
702
- * @returns The name, e.g. `'C major'` or `'A minor'`.
703
- */
704
- toString() {
705
- return `${this.#tonic.name} ${this.isMinor ? "minor" : "major"}`;
706
- }
707
- };
708
-
709
- // src/model/progression.ts
710
- var Progression = class _Progression {
711
- #chords;
712
- #key;
713
- /**
714
- * Wrap a chord sequence.
715
- *
716
- * @param chords The chords in order; the array is copied.
717
- * @param key Optional key context for analysis methods.
718
- */
719
- constructor(chords, key) {
720
- this.#chords = Object.freeze([...chords]);
721
- this.#key = key;
722
- }
723
- /**
724
- * Build a progression from the {@link ChordSpan} records the generators
725
- * return, keeping their order.
726
- *
727
- * The spans' `startBeat`, `degree`, and `secondaryDominant` are analysis
728
- * annotations that a chord sequence does not carry; only the harmony crosses
729
- * over. Keep the spans themselves if the timing matters.
730
- *
731
- * @param spans The chord spans, in order.
732
- * @param key Optional key context for the analysis methods.
733
- * @returns The progression.
734
- * @example
735
- * ```ts
736
- * import { generateProgression, Key, Progression } from '@libraz/libcantus';
737
- * const key = Key.major('C');
738
- * const spans = generateProgression({ key: key.scale, style: 'dance', bars: 4 });
739
- * Progression.fromSpans(spans, key).roman();
740
- * ```
741
- */
742
- static fromSpans(spans, key) {
743
- const chords = spans.map((span) => {
744
- const chord = Chord.from(makeChord(span.rootPc, span.quality, span.bassPc));
745
- return key === void 0 ? chord : chord.withKey(key);
746
- });
747
- return key === void 0 ? new _Progression(chords) : new _Progression(chords, key);
748
- }
749
- /**
750
- * Rebuild a progression from its {@link Progression.toJSON} output.
751
- *
752
- * @param data The serialized chords and key.
753
- * @returns The progression.
754
- */
755
- static fromJSON(data) {
756
- const key = data.key === void 0 ? void 0 : Key.fromJSON(data.key);
757
- const chords = data.chords.map((chord) => Chord.fromJSON(chord));
758
- return key === void 0 ? new _Progression(chords) : new _Progression(chords, key);
759
- }
760
- /**
761
- * The chord sequence.
762
- *
763
- * The array is the progression's own and is frozen rather than copied, so
764
- * reading it in a loop stays linear.
765
- */
766
- get chords() {
767
- return this.#chords;
768
- }
769
- /** The carried key context, if any. */
770
- get key() {
771
- return this.#key;
772
- }
773
- /** The number of chords. */
774
- get length() {
775
- return this.#chords.length;
776
- }
777
- /**
778
- * The chord at an index.
779
- *
780
- * @param index 0-based position; a negative index counts from the end.
781
- * @returns The chord, or undefined when the index is out of range.
782
- */
783
- at(index) {
784
- return this.#chords.at(index);
785
- }
786
- /** Iterate the chords in order, so a progression works with `for...of`. */
787
- [Symbol.iterator]() {
788
- return this.#chords[Symbol.iterator]();
789
- }
790
- /**
791
- * Whether another progression holds the same chords in the same order.
792
- *
793
- * The key context is not compared: it is an analysis lens, not part of the
794
- * harmony. Chord equality follows {@link Chord.equals}.
795
- *
796
- * @param other The progression to compare.
797
- * @returns True when the chord sequences match.
798
- */
799
- equals(other) {
800
- if (this.#chords.length !== other.length) {
801
- return false;
802
- }
803
- return this.#chords.every((chord, index) => {
804
- const theirs = other.at(index);
805
- return theirs !== void 0 && chord.equals(theirs);
806
- });
807
- }
808
- /**
809
- * A copy of this progression with a chord appended.
810
- *
811
- * @param chord The chord to append.
812
- * @returns The new progression.
813
- */
814
- add(chord) {
815
- return new _Progression([...this.#chords, chord], this.#key);
816
- }
817
- /**
818
- * A copy of this progression carrying the given key context.
819
- *
820
- * @param key The key context to attach.
821
- * @returns The new progression.
822
- */
823
- withKey(key) {
824
- return new _Progression(this.#chords, key);
825
- }
826
- /**
827
- * Voice the progression with smooth voice leading.
828
- *
829
- * @param opts Voicing options; defaults to four SATB voices.
830
- * @returns One ascending voicing (MIDI pitches) per chord.
831
- * @throws If any chord admits no voicing within the given ranges.
832
- */
833
- voice(opts) {
834
- return voiceProgression(
835
- this.#chords.map((chord) => chord.data),
836
- opts
837
- );
838
- }
839
- /**
840
- * The Roman numeral of each chord in a key.
841
- *
842
- * @param key Key to analyze in; falls back to the carried context.
843
- * @returns One numeral per chord.
844
- * @throws If no key is given and none is carried.
845
- */
846
- roman(key) {
847
- const resolved = this.#resolveKey(key);
848
- return this.#chords.map((chord) => chord.roman(resolved));
849
- }
850
- /**
851
- * The harmonic function of each chord in a key.
852
- *
853
- * @param key Key to analyze in; falls back to the carried context.
854
- * @returns One function per chord.
855
- * @throws If no key is given and none is carried.
856
- */
857
- functions(key) {
858
- const resolved = this.#resolveKey(key);
859
- return this.#chords.map((chord) => chord.function(resolved));
860
- }
861
- /**
862
- * Analyze every chord and classify the closing cadence.
863
- *
864
- * The cadence is detected on the final chord pair and is null when the
865
- * progression has fewer than two chords.
866
- *
867
- * @param key Key to analyze in; falls back to the carried context.
868
- * @returns Per-chord analyses and the closing cadence.
869
- * @throws If no key is given and none is carried.
870
- */
871
- analyze(key) {
872
- const resolved = this.#resolveKey(key);
873
- const chords = this.#chords.map((chord) => chord.analyze(resolved));
874
- const from = this.#chords[this.#chords.length - 2];
875
- const to = this.#chords[this.#chords.length - 1];
876
- const cadence = from !== void 0 && to !== void 0 ? detectCadence(from.data, to.data, resolved.scale) : null;
877
- return { chords, cadence };
878
- }
879
- /**
880
- * The plain progression data, for JSON serialization.
881
- *
882
- * Private class fields do not serialize, so an explicit `toJSON` keeps
883
- * `JSON.stringify(progression)` from collapsing to `{}`. The chords are
884
- * emitted as plain data and the carried key, when present, as its own data.
885
- *
886
- * @returns The chord data sequence and the carried key, if any.
887
- */
888
- /**
889
- * Transpose every chord by a number of semitones.
890
- *
891
- * A carried key moves with the chords, so the progression keeps its degrees
892
- * and functions in the new key.
893
- *
894
- * @param semitones The signed semitone offset.
895
- * @returns The transposed progression.
896
- * @example
897
- * ```ts
898
- * import { Chord, Progression } from '@libraz/libcantus';
899
- * new Progression([Chord.parse('C'), Chord.parse('G')]).transpose(2).toString(); // 'D A'
900
- * ```
901
- */
902
- transpose(semitones) {
903
- const key = this.#key?.transpose(semitones);
904
- const chords = this.#chords.map((chord) => {
905
- const moved = chord.transpose(semitones);
906
- return key !== void 0 && moved.key === void 0 ? moved.withKey(key) : moved;
907
- });
908
- return key === void 0 ? new _Progression(chords) : new _Progression(chords, key);
909
- }
910
- /**
911
- * The chord symbols separated by spaces, so a template literal or a log line
912
- * reads as the progression.
913
- *
914
- * @returns The symbols in order, e.g. `'C Am F G'`.
915
- */
916
- toString() {
917
- return this.#chords.map((chord) => chord.symbol()).join(" ");
918
- }
919
- toJSON() {
920
- return {
921
- chords: this.#chords.map((chord) => chord.data),
922
- key: this.#key?.toJSON()
923
- };
924
- }
925
- /** Resolve the key for an analysis method: explicit first, then carried. */
926
- #resolveKey(key) {
927
- const resolved = key ?? this.#key;
928
- if (resolved === void 0) {
929
- throw new InvalidInputError(
930
- "progression has no key context; pass a Key or attach one with withKey()"
931
- );
932
- }
933
- return resolved;
934
- }
935
- };
936
-
937
- // src/model/chord.ts
938
- function hintMatches(hint, pc) {
939
- return hint !== void 0 && pc !== void 0 && pitchClassOf(noteToPitchClass(hint)) === pitchClassOf(pc);
940
- }
941
- function copyChord(data) {
942
- const copy = {
943
- rootPc: data.rootPc,
944
- quality: data.quality,
945
- intervals: [...data.intervals]
946
- };
947
- if (data.bassPc !== void 0) {
948
- copy.bassPc = data.bassPc;
949
- }
950
- if (hintMatches(data.rootSpelling, data.rootPc) && data.rootSpelling !== void 0) {
951
- copy.rootSpelling = { letter: data.rootSpelling.letter, alter: data.rootSpelling.alter };
952
- }
953
- if (hintMatches(data.bassSpelling, data.bassPc) && data.bassSpelling !== void 0) {
954
- copy.bassSpelling = { letter: data.bassSpelling.letter, alter: data.bassSpelling.alter };
955
- }
956
- return copy;
957
- }
958
- function deriveBassSpelling(chord, key) {
959
- const bassPc = chord.bassPc;
960
- if (bassPc === void 0) {
961
- return void 0;
962
- }
963
- const root = chord.rootSpelling;
964
- if (root !== void 0) {
965
- const index = chord.intervals.findIndex((i) => pitchClassOf(chord.rootPc + i) === bassPc);
966
- const tone = index >= 0 ? spellChordFromRoot(chord, root)[index] : void 0;
967
- if (tone !== void 0) {
968
- return { letter: tone.letter, alter: tone.alter };
969
- }
970
- }
971
- if (key === void 0) {
972
- return void 0;
973
- }
974
- const spelled = spellPitchClass(bassPc, key.tonic.data, key.scale);
975
- return { letter: spelled.letter, alter: spelled.alter };
976
- }
977
- var Chord = class _Chord {
978
- /** Exactly what the caller supplied: any spelling here is the caller's own. */
979
- #given;
980
- #key;
981
- /**
982
- * Wrap a plain chord object.
983
- *
984
- * @param data The chord; it is copied, never retained or mutated.
985
- * @param key Optional key context for analysis methods.
986
- */
987
- constructor(data, key) {
988
- this.#given = copyChord(data);
989
- this.#key = key;
990
- }
991
- /**
992
- * The chord data with any missing spelling hint filled in from the key.
993
- *
994
- * Derived spellings are computed on read rather than baked in at construction,
995
- * so re-attaching a different key re-spells the chord instead of carrying the
996
- * first key's letters forever. A spelling the caller supplied always wins.
997
- */
998
- get #data() {
999
- const out = copyChord(this.#given);
1000
- const key = this.#key;
1001
- if (out.rootSpelling === void 0 && key !== void 0) {
1002
- out.rootSpelling = spellPitchClass(out.rootPc, key.tonic.data, key.scale);
1003
- }
1004
- if (out.bassSpelling === void 0) {
1005
- const bass = deriveBassSpelling(out, key);
1006
- if (bass !== void 0) {
1007
- out.bassSpelling = bass;
1008
- }
1009
- }
1010
- return out;
1011
- }
1012
- /**
1013
- * Build a chord from a root and quality.
1014
- *
1015
- * @param root Root as a note name (e.g. `'Eb'`) or a pitch class.
1016
- * @param quality The chord quality.
1017
- * @param bass Optional slash-chord bass, as a note name (e.g. `'Bb'`) or a
1018
- * pitch class. A named bass keeps its own spelling.
1019
- * @returns The chord (without key context).
1020
- */
1021
- static of(root, quality, bass) {
1022
- const bassNote = typeof bass === "string" ? Note.of(bass) : void 0;
1023
- const bassPc = bassNote !== void 0 ? bassNote.pitchClass : bass;
1024
- const rootNote = typeof root === "string" ? Note.of(root) : void 0;
1025
- const data = makeChord(
1026
- rootNote !== void 0 ? rootNote.pitchClass : root,
1027
- quality,
1028
- bassPc
1029
- );
1030
- if (rootNote !== void 0) {
1031
- data.rootSpelling = { letter: rootNote.letter, alter: rootNote.alter };
1032
- }
1033
- if (bassNote !== void 0) {
1034
- data.bassSpelling = { letter: bassNote.letter, alter: bassNote.alter };
1035
- }
1036
- return new _Chord(data);
1037
- }
1038
- /**
1039
- * Wrap an existing plain chord object.
1040
- *
1041
- * @param data The plain chord.
1042
- * @returns The wrapped chord (without key context).
1043
- */
1044
- static from(data) {
1045
- return new _Chord(data);
1046
- }
1047
- /**
1048
- * Alias of {@link Chord.from}, matching the `fromData` factory on the other
1049
- * classes.
1050
- *
1051
- * @param data The plain chord.
1052
- * @returns The wrapped chord (without key context).
1053
- */
1054
- static fromData(data) {
1055
- return new _Chord(data);
1056
- }
1057
- /**
1058
- * Rebuild a chord from its {@link Chord.toJSON} output.
1059
- *
1060
- * The key context is not serialized, so the result carries none; re-attach
1061
- * one with {@link Chord.withKey}.
1062
- *
1063
- * @param data The serialized chord.
1064
- * @returns The wrapped chord.
1065
- */
1066
- static fromJSON(data) {
1067
- return new _Chord(data);
1068
- }
1069
- /**
1070
- * Parse a lead-sheet chord symbol (e.g. `'Cmaj7'`, `'F#m7b5'`, `'C/G'`).
1071
- *
1072
- * @param symbol The chord symbol.
1073
- * @returns The chord (without key context).
1074
- * @throws If the root or quality is not recognized.
1075
- */
1076
- static parse(symbol) {
1077
- return new _Chord(parseChordSymbol(symbol));
1078
- }
1079
- /**
1080
- * Identify the chords matching a set of pitches, best interpretation first.
1081
- *
1082
- * @param pitches MIDI pitches or bare pitch classes.
1083
- * @param opts How to interpret the input; see {@link DetectChordOptions}.
1084
- * @returns Ranked chord interpretations (may be empty).
1085
- */
1086
- static detect(pitches, opts) {
1087
- return detectChord(pitches, opts).map(
1088
- (match) => new _Chord(makeChord(match.rootPc, match.quality, match.bassPc))
1089
- );
1090
- }
1091
- /**
1092
- * Identify the chords matching a set of pitches, keeping each match's
1093
- * recognition metadata beside the chord.
1094
- *
1095
- * {@link Chord.detect} discards the confidence signals a recognition UI needs
1096
- * — whether the set matched exactly, which chord tones were missing, which
1097
- * input notes were foreign, and which inversion the bass implies.
1098
- *
1099
- * @param pitches MIDI pitches or bare pitch classes.
1100
- * @param opts How to interpret the input; see {@link DetectChordOptions}.
1101
- * @returns Ranked interpretations, each with its chord and its match record.
1102
- * @example
1103
- * ```ts
1104
- * import { Chord } from '@libraz/libcantus';
1105
- * const [best] = Chord.detectMatches([60, 64, 67]);
1106
- * best?.match.exact; // true
1107
- * ```
1108
- */
1109
- static detectMatches(pitches, opts) {
1110
- return detectChord(pitches, opts).map((match) => ({
1111
- chord: new _Chord(makeChord(match.rootPc, match.quality, match.bassPc)),
1112
- match
1113
- }));
1114
- }
1115
- /**
1116
- * The single best chord interpretation of a pitch set.
1117
- *
1118
- * @param pitches MIDI pitches or bare pitch classes.
1119
- * @param opts How to interpret the input; see {@link DetectChordOptions}.
1120
- * @returns The top-ranked chord, or null when nothing matches.
1121
- */
1122
- static detectBest(pitches, opts) {
1123
- const best = detectChordBest(pitches, opts);
1124
- return best === null ? null : new _Chord(best);
1125
- }
1126
- /** The root pitch class (0..11). */
1127
- get rootPc() {
1128
- return this.#data.rootPc;
1129
- }
1130
- /** The chord quality. */
1131
- get quality() {
1132
- return this.#data.quality;
1133
- }
1134
- /** A copy of the semitone offsets above the root. */
1135
- get intervals() {
1136
- return [...this.#data.intervals];
1137
- }
1138
- /** The slash-chord bass pitch class, or undefined in root position. */
1139
- get bassPc() {
1140
- return this.#data.bassPc;
1141
- }
1142
- /**
1143
- * A copy of the underlying plain chord object, including the spellings
1144
- * derived from any attached key.
1145
- */
1146
- get data() {
1147
- return this.#data;
1148
- }
1149
- /** The carried key context, if any. */
1150
- get key() {
1151
- return this.#key;
1152
- }
1153
- /**
1154
- * A copy of this chord carrying the given key context.
1155
- *
1156
- * Only a spelling the caller supplied (via `Chord.parse`, `Chord.of` with a
1157
- * named root, or plain data carrying a hint) survives; a spelling that came
1158
- * from a previously attached key is re-derived, so re-keying a progression
1159
- * during a modulation does not keep the old key's letters and the order of
1160
- * `withKey` calls does not affect the result.
1161
- *
1162
- * @param key The key context to attach.
1163
- * @returns The new chord.
1164
- */
1165
- withKey(key) {
1166
- return new _Chord(this.#given, key);
1167
- }
1168
- /**
1169
- * The chord's sorted, deduplicated pitch classes.
1170
- *
1171
- * @returns Pitch classes ascending in [0, 11].
1172
- */
1173
- pitchClasses() {
1174
- return chordPitchClasses(this.#data);
1175
- }
1176
- /**
1177
- * The chord's Roman numeral in a key.
1178
- *
1179
- * @param key Key to analyze in; falls back to the carried context.
1180
- * @returns The Roman numeral string.
1181
- * @throws If no key is given and none is carried.
1182
- */
1183
- roman(key) {
1184
- return chordToRoman(this.#data, this.#resolveKey(key).scale);
1185
- }
1186
- /**
1187
- * The chord's harmonic function (tonic / subdominant / dominant) in a key.
1188
- *
1189
- * @param key Key to analyze in; falls back to the carried context.
1190
- * @returns The harmonic function.
1191
- * @throws If no key is given and none is carried.
1192
- */
1193
- function(key) {
1194
- return functionOf(this.#data, this.#resolveKey(key).scale);
1195
- }
1196
- /**
1197
- * Full functional analysis: function, borrowing, and Roman numeral.
1198
- *
1199
- * @param key Key to analyze in; falls back to the carried context.
1200
- * @returns The chord analysis.
1201
- * @throws If no key is given and none is carried.
1202
- */
1203
- analyze(key) {
1204
- return analyzeChord(this.#data, this.#resolveKey(key).scale);
1205
- }
1206
- /**
1207
- * Whether the chord is borrowed from the parallel mode (modal interchange).
1208
- *
1209
- * @param key Key to analyze in; falls back to the carried context.
1210
- * @returns True if the chord is borrowed.
1211
- * @throws If no key is given and none is carried.
1212
- */
1213
- isBorrowed(key) {
1214
- return isBorrowedChord(this.#data, this.#resolveKey(key).scale);
1215
- }
1216
- /**
1217
- * The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
1218
- *
1219
- * @param key Key to analyze in; falls back to the carried context.
1220
- * @returns The borrowing source, or null.
1221
- * @throws If no key is given and none is carried.
1222
- */
1223
- borrowedSource(key) {
1224
- return borrowedSource(this.#data, this.#resolveKey(key).scale);
1225
- }
1226
- /**
1227
- * The chord rendered as a lead-sheet symbol (e.g. `'Cmaj7'`, `'F#m7'`, `'C/G'`).
1228
- *
1229
- * @param opts Set `flats: true` to spell the root/bass with flats.
1230
- * @returns The chord symbol.
1231
- */
1232
- symbol(opts) {
1233
- return formatChordSymbol(this.#data, opts);
1234
- }
1235
- /**
1236
- * Realize the chord as one MIDI pitch per voice, ascending.
1237
- *
1238
- * A chord that carries a key passes it to the voicer, so the leading tone is
1239
- * not doubled; an explicit `opts.key` overrides it.
1240
- *
1241
- * @param opts Voicing options; defaults to four SATB voices.
1242
- * @returns MIDI pitches, ascending, one per voice.
1243
- * @throws If no voicing fits the given ranges.
1244
- */
1245
- voice(opts) {
1246
- const key = opts?.key ?? this.#key?.scale;
1247
- return voiceChord(this.#data, key === void 0 ? opts : { ...opts, key });
1248
- }
1249
- /**
1250
- * Realize the chord as a single styled voicing (`close`, `drop2`, `drop3`,
1251
- * `shell`, or `rootless`), optionally constraining the top voice.
1252
- *
1253
- * @param opts Styled-voicing options; defaults to a close-position voicing.
1254
- * @returns MIDI pitches, ascending.
1255
- */
1256
- styledVoicing(opts) {
1257
- return voiceChordStyled(this.#data, opts);
1258
- }
1259
- /**
1260
- * The negative-harmony mirror of the chord about the key's tonic–dominant
1261
- * axis (major becomes minor and vice versa).
1262
- *
1263
- * @param key Key providing the reflection axis; falls back to the carried
1264
- * context.
1265
- * @returns The mirrored chord, keeping any key context.
1266
- * @throws If no key is given and none is carried.
1267
- */
1268
- negativeHarmony(key) {
1269
- const resolved = this.#resolveKey(key);
1270
- return new _Chord(negativeHarmonyMirror(this.#data, resolved.scale), key ?? this.#key);
1271
- }
1272
- /**
1273
- * The n-th inversion: a copy whose bass is the chord tone `n` steps above the
1274
- * root in the interval template (`invert(1)` puts the third in the bass).
1275
- * `n` wraps around the template length; negative values count backwards.
1276
- *
1277
- * `invert(0)` (and any `n` that wraps to it) is root position, so it carries
1278
- * no slash bass and equals the original chord.
1279
- *
1280
- * @param n The inversion number.
1281
- * @returns The inverted chord, keeping any key context.
1282
- * @throws If the chord has no intervals.
1283
- */
1284
- invert(n) {
1285
- const data = copyChord(this.#given);
1286
- const intervals = data.intervals;
1287
- const length = intervals.length;
1288
- if (length === 0) {
1289
- throw new InvalidInputError("cannot invert a chord with no intervals");
1290
- }
1291
- const index = (n % length + length) % length;
1292
- delete data.bassSpelling;
1293
- if (index === 0) {
1294
- delete data.bassPc;
1295
- } else {
1296
- data.bassPc = pitchClassOf(data.rootPc + (intervals[index] ?? 0));
1297
- }
1298
- return new _Chord(data, this.#key);
1299
- }
1300
- /**
1301
- * Transpose the chord by a number of semitones.
1302
- *
1303
- * The quality and interval template are carried over, so a chord that a
1304
- * symbol round-trip could not express — a custom interval set, an inversion —
1305
- * survives. A carried key moves with the chord, so the transposed chord keeps
1306
- * the same degree and function inside the transposed key.
1307
- *
1308
- * @param semitones The signed semitone offset.
1309
- * @returns The transposed chord, in the transposed key when one is carried.
1310
- * @example
1311
- * ```ts
1312
- * import { Chord } from '@libraz/libcantus';
1313
- * Chord.parse('C/G').transpose(2).symbol(); // 'D/A'
1314
- * ```
1315
- */
1316
- transpose(semitones) {
1317
- const moved = transposeChord(this.#given, semitones);
1318
- return new _Chord(moved, this.#key?.transpose(semitones));
1319
- }
1320
- /**
1321
- * The named scales that fit over this chord, best fit first, rooted on the
1322
- * chord root.
1323
- *
1324
- * @returns The matching scales.
1325
- */
1326
- scales() {
1327
- return chordScales(this.#data);
1328
- }
1329
- /**
1330
- * The available tensions (usable non-chord, non-avoid scale tones) of a
1331
- * scale over this chord.
1332
- *
1333
- * @param scaleName A named scale, rooted on the chord root.
1334
- * @returns Tension pitch classes, ascending in [0, 11].
1335
- * @throws If `scaleName` is not a built-in scale.
1336
- */
1337
- tensions(scaleName) {
1338
- return availableTensions(this.#data, scaleName);
1339
- }
1340
- /**
1341
- * The avoid notes (scale tones a semitone above a chord tone) of a scale
1342
- * over this chord.
1343
- *
1344
- * @param scaleName A named scale, rooted on the chord root.
1345
- * @returns Avoid-note pitch classes, ascending in [0, 11].
1346
- * @throws If `scaleName` is not a built-in scale.
1347
- */
1348
- avoidNotes(scaleName) {
1349
- return avoidNotes(this.#data, scaleName);
1350
- }
1351
- /**
1352
- * Spell the chord tones with letter names, root first, in the key's spelling.
1353
- *
1354
- * A chord that already knows how its root is spelled — one from
1355
- * `Chord.parse`, or `Chord.of` with a named root — can spell itself with no
1356
- * key at all; a key is only needed to choose a spelling for a bare pitch
1357
- * class.
1358
- *
1359
- * A slash bass outside the chord tones is appended, so the spelled notes
1360
- * are the notes the chord sounds — the same set {@link Chord.pitchClasses}
1361
- * reports.
1362
- *
1363
- * @param key Key providing the spelled tonic; falls back to the carried
1364
- * context, then to the chord's own root spelling.
1365
- * @returns Spelled octave-less notes in the chord's own (tertian) order,
1366
- * with any foreign slash bass last.
1367
- * @throws If no key is given, none is carried, and the chord has no root
1368
- * spelling of its own.
1369
- */
1370
- spell(key) {
1371
- const data = this.#data;
1372
- const resolved = key ?? this.#key;
1373
- let tones;
1374
- if (resolved === void 0) {
1375
- const root = data.rootSpelling;
1376
- if (root === void 0) {
1377
- throw new InvalidInputError(
1378
- "chord has no key context and no root spelling; pass a Key, attach one with withKey(), or build the chord from a symbol"
1379
- );
1380
- }
1381
- tones = spellChordFromRoot(data, root);
1382
- } else {
1383
- tones = spellChord(data, resolved.tonic.data, resolved.scale);
1384
- }
1385
- const bassPc = data.bassPc;
1386
- const bass = data.bassSpelling;
1387
- if (bassPc !== void 0 && bass !== void 0 && !tones.some((tone) => pitchClassOf(noteToPitchClass(tone)) === pitchClassOf(bassPc))) {
1388
- tones = [...tones, { letter: bass.letter, alter: bass.alter }];
1389
- }
1390
- return tones.map((note) => new Note(note));
1391
- }
1392
- /**
1393
- * Start a progression with this chord followed by others, carrying this
1394
- * chord's key context (if any).
1395
- *
1396
- * @param others The chords following this one.
1397
- * @returns The progression.
1398
- */
1399
- progressionTo(...others) {
1400
- return new Progression([this, ...others], this.#key);
1401
- }
1402
- /**
1403
- * Whether another chord has the same root, quality, intervals, and bass.
1404
- * Key context is not compared.
1405
- *
1406
- * @param other The chord to compare.
1407
- * @returns True if the chord data is identical.
1408
- */
1409
- equals(other) {
1410
- const a = this.#data;
1411
- const b = other.data;
1412
- return a.rootPc === b.rootPc && a.quality === b.quality && a.bassPc === b.bassPc && a.intervals.length === b.intervals.length && a.intervals.every((interval, i) => interval === b.intervals[i]);
1413
- }
1414
- /**
1415
- * The plain chord data, for JSON serialization.
1416
- *
1417
- * @returns A copy of the underlying plain chord object.
1418
- */
1419
- toJSON() {
1420
- return this.data;
1421
- }
1422
- /**
1423
- * The chord symbol, so a template literal or a log line reads as the chord.
1424
- *
1425
- * @returns The symbol, e.g. `'Cmaj7'`.
1426
- */
1427
- toString() {
1428
- return this.symbol();
1429
- }
1430
- /** Resolve the key for an analysis method: explicit first, then carried. */
1431
- #resolveKey(key) {
1432
- const resolved = key ?? this.#key;
1433
- if (resolved === void 0) {
1434
- throw new InvalidInputError(
1435
- "chord has no key context; pass a Key or attach one with withKey()"
1436
- );
1437
- }
1438
- return resolved;
1439
- }
1440
- };
1441
-
1442
- export {
1443
- Interval,
1444
- Note,
1445
- Key,
1446
- Progression,
1447
- Chord
1448
- };
1449
- //# sourceMappingURL=chunk-EHVEBWM5.js.map