@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,46 @@
1
+ import {
2
+ Arrangement,
3
+ BudgetExceededError,
4
+ Chord,
5
+ Composer,
6
+ Duration,
7
+ Instrument,
8
+ Interval,
9
+ InvalidInputError,
10
+ Key,
11
+ Meter,
12
+ Motif,
13
+ NoSolutionError,
14
+ Note,
15
+ NoteSafety,
16
+ Progression,
17
+ Rhythm,
18
+ Score,
19
+ Tempo,
20
+ Timeline,
21
+ Tuning,
22
+ Voicing
23
+ } from "../chunk-4LABHUBW.js";
24
+ export {
25
+ Arrangement,
26
+ BudgetExceededError,
27
+ Chord,
28
+ Composer,
29
+ Duration,
30
+ Instrument,
31
+ Interval,
32
+ InvalidInputError,
33
+ Key,
34
+ Meter,
35
+ Motif,
36
+ NoSolutionError,
37
+ Note,
38
+ NoteSafety,
39
+ Progression,
40
+ Rhythm,
41
+ Score,
42
+ Tempo,
43
+ Timeline,
44
+ Tuning,
45
+ Voicing
46
+ };
@@ -0,0 +1,365 @@
1
+ import { a as Articulation } from './index-C9MYbuKS.js';
2
+
3
+ /**
4
+ * Every limb a percussionist strikes with, in declaration order.
5
+ *
6
+ * @category Core
7
+ */
8
+ declare const LIMBS: readonly ["rightHand", "leftHand", "rightFoot", "leftFoot"];
9
+ /**
10
+ * One limb of a percussionist.
11
+ *
12
+ * @category Core
13
+ */
14
+ type Limb = (typeof LIMBS)[number];
15
+ /**
16
+ * Fields every instrument profile carries, whatever its family.
17
+ *
18
+ * @category Core
19
+ */
20
+ type InstrumentProfileCommon = {
21
+ /** Instrument name, for issue messages and for the caller's own display. */
22
+ name: string;
23
+ /** Techniques this instrument can produce; anything else it cannot play. */
24
+ articulations: readonly Articulation[];
25
+ /** Greatest number of notes that can sound at once. */
26
+ polyphony: number;
27
+ };
28
+ /**
29
+ * A fretted or fretless string instrument, described by what it is rather than
30
+ * by the range it happens to have.
31
+ *
32
+ * The sounding range follows from `tuning` and `frets`: string `s` sounds
33
+ * `tuning[s] .. tuning[s] + frets`. Storing `[min, max]` instead would make a
34
+ * five-string bass, a drop tuning, a seven-string guitar and an extended-range
35
+ * neck four unrelated special cases, and would leave "the neck is not long
36
+ * enough" indistinguishable from "the note is below the instrument".
37
+ *
38
+ * @category Core
39
+ */
40
+ type StringedProfile = InstrumentProfileCommon & {
41
+ kind: 'stringed';
42
+ /** Open-string MIDI pitch per string, lowest-sounding string first. */
43
+ tuning: readonly number[];
44
+ /** Highest fret number; fret 0 is the open string. */
45
+ frets: number;
46
+ /** Greatest fret span one hand can hold down at once. */
47
+ maxStretch: number;
48
+ /**
49
+ * The neck has no frets. Positions are continuous, so intonation is the
50
+ * player's and a slide is unbroken; in twelve-tone equal temperament the
51
+ * positions coincide with fret numbers, so range and stretch are read the
52
+ * same way.
53
+ */
54
+ fretless?: boolean;
55
+ };
56
+ /**
57
+ * A percussion setup, described by the voices within reach of each limb.
58
+ *
59
+ * A kit's constraint is not range but limbs: a voice no limb can reach is not
60
+ * on the instrument, and two voices needing the same limb at the same instant
61
+ * cannot both sound.
62
+ *
63
+ * @category Core
64
+ */
65
+ type PercussionProfile = InstrumentProfileCommon & {
66
+ kind: 'percussion';
67
+ /** The limbs the player has available. */
68
+ limbs: readonly Limb[];
69
+ /** Limbs that can strike each voice, in preference order, keyed by MIDI note. */
70
+ reach: Readonly<Record<number, readonly Limb[]>>;
71
+ /**
72
+ * Voices dubbed over the kit on a pass of their own, by MIDI note number.
73
+ *
74
+ * A tambourine or a shaker riding a groove whose backbeat already commits
75
+ * both hands is a second pass, not a third hand: it is played over the kit,
76
+ * so it takes no limb from the kit and none from another overdub. Such a
77
+ * voice is still held in a hand on its own pass, so it keeps its `reach`
78
+ * entry and remains a voice of the instrument; this names which of them are
79
+ * played that way.
80
+ */
81
+ overdub?: readonly number[];
82
+ };
83
+ /**
84
+ * An instrument the library can check a passage against.
85
+ *
86
+ * @category Core
87
+ */
88
+ type InstrumentProfile = StringedProfile | PercussionProfile;
89
+ declare const checked: unique symbol;
90
+ /**
91
+ * A neck whose every field has been checked against the domain it declares.
92
+ *
93
+ * @category Core
94
+ */
95
+ type ValidatedStringedProfile = StringedProfile & {
96
+ readonly [checked]: true;
97
+ };
98
+ /**
99
+ * A kit whose every field has been checked against the domain it declares.
100
+ *
101
+ * @category Core
102
+ */
103
+ type ValidatedPercussionProfile = PercussionProfile & {
104
+ readonly [checked]: true;
105
+ };
106
+ /**
107
+ * A profile whose every field has been checked against the domain it declares.
108
+ *
109
+ * The mark is carried by the type alone — nothing is added to the object, so a
110
+ * validated profile serializes exactly as the plain one it was made from. Its
111
+ * only source is {@link toInstrumentProfile}, which is what makes the mark worth
112
+ * anything: the routines that read a profile note by note take this rather than
113
+ * a plain {@link InstrumentProfile}, so a path that skipped the checks does not
114
+ * compile instead of failing on the one passage that happens to expose it.
115
+ *
116
+ * @category Core
117
+ */
118
+ type ValidatedProfile = ValidatedStringedProfile | ValidatedPercussionProfile;
119
+ /**
120
+ * Anything that names an instrument: a plain {@link InstrumentProfile}, or a
121
+ * value that serializes to one such as the `Instrument` class.
122
+ *
123
+ * Every entry point that takes an instrument takes this, so a caller holding
124
+ * the class hands it over as it is instead of unwrapping it for one call and
125
+ * wrapping it again for the next.
126
+ *
127
+ * @category Core
128
+ */
129
+ type InstrumentProfileLike = InstrumentProfile | {
130
+ /** The profile data this value stands for. */
131
+ toJSON(): InstrumentProfile;
132
+ };
133
+ /**
134
+ * Resolve any instrument-shaped value to a plain {@link InstrumentProfile}.
135
+ *
136
+ * The counterpart of {@link toNoteData} for instruments: an entry point takes
137
+ * whatever form the caller has — the profile a project file holds, one of the
138
+ * built-in profiles, or an `Instrument` instance — and gets one shape back. An
139
+ * instance is accepted through its `toJSON` method rather than by its type,
140
+ * because the core layer cannot import the model layer that defines the class.
141
+ *
142
+ * @param value A plain profile, or a value whose `toJSON` returns one.
143
+ * @param name What the instrument is called in an error message, so a caller
144
+ * holding several of them hears which one was malformed.
145
+ * @returns The validated profile.
146
+ * @throws If the value names no instrument, or the instrument it names is
147
+ * contradictory — a neck with no strings, a fret count that is no count, or a
148
+ * kit no limb reaches.
149
+ * @category Core
150
+ */
151
+ declare function toInstrumentProfile(value: InstrumentProfileLike, name?: string): ValidatedProfile;
152
+ /**
153
+ * Resolve any instrument-shaped value to a plain {@link StringedProfile}.
154
+ *
155
+ * What {@link toInstrumentProfile} is for an entry point that reads any
156
+ * instrument, this is for one that only has a neck to work with: a bass line
157
+ * placed on strings and frets cannot be written for a kit, and saying so by
158
+ * name is more use than a missing `tuning` surfacing later as a note the
159
+ * generator could not place.
160
+ *
161
+ * @param value A plain profile, or a value whose `toJSON` returns one.
162
+ * @param name What the instrument is called in an error message.
163
+ * @returns The validated profile, narrowed to the stringed family.
164
+ * @throws If the value names no instrument, or names one with no strings.
165
+ * @category Core
166
+ */
167
+ declare function toStringedProfile(value: InstrumentProfileLike, name?: string): ValidatedStringedProfile;
168
+ /**
169
+ * A fretting-hand position: which string, and how far up the neck.
170
+ *
171
+ * @category Core
172
+ */
173
+ type StringFingering = {
174
+ /** Index into the `tuning` of a {@link StringedProfile}. */
175
+ string: number;
176
+ /** Fret number; 0 is the open string. */
177
+ fret: number;
178
+ };
179
+ /**
180
+ * The lowest and highest pitch an instrument sounds.
181
+ *
182
+ * For a string instrument this is derived from the tuning and the fret count,
183
+ * never stored; for a kit it is the extent of the voices the player's limbs
184
+ * reach. The range is not necessarily gapless — use {@link canSound} to ask
185
+ * about one pitch.
186
+ *
187
+ * @param profile The instrument.
188
+ * @returns The extreme sounding pitches, inclusive.
189
+ *
190
+ * @example
191
+ * ```ts
192
+ * import { BASS_5_STRING, instrumentRange } from '@libraz/libcantus';
193
+ * instrumentRange(BASS_5_STRING).low; // 23, low B
194
+ * ```
195
+ * @category Core
196
+ */
197
+ declare function instrumentRange(profile: InstrumentProfileLike): {
198
+ low: number;
199
+ high: number;
200
+ };
201
+ /**
202
+ * Whether the instrument has this pitch at all.
203
+ *
204
+ * This is the first of the three playability layers: no amount of skill or
205
+ * rehearsal puts a note on an instrument that has no position for it.
206
+ *
207
+ * @param profile The instrument.
208
+ * @param pitch MIDI pitch.
209
+ * @returns True when some string and fret, or some limb the player has,
210
+ * produces it.
211
+ * @category Core
212
+ */
213
+ declare function canSound(profile: InstrumentProfileLike, pitch: number): boolean;
214
+ /**
215
+ * Every position on the neck that sounds a pitch, lowest string first.
216
+ *
217
+ * @param profile The instrument.
218
+ * @param pitch MIDI pitch.
219
+ * @returns One entry per string that reaches the pitch; empty when none does.
220
+ * @category Core
221
+ */
222
+ declare function fingeringsFor(profile: InstrumentProfileLike, pitch: number): StringFingering[];
223
+ /**
224
+ * Move a pitch by whole octaves until the instrument can sound it.
225
+ *
226
+ * This is what a player does with a line written below the instrument: the note
227
+ * comes back an octave up, keeping its pitch class and its place in the phrase.
228
+ * Substituting a different scale degree, or refusing the passage outright, is
229
+ * the wrong answer for a bass line.
230
+ *
231
+ * @param pitch MIDI pitch to place.
232
+ * @param profile The instrument.
233
+ * @returns The nearest octave transposition the instrument sounds, taking the
234
+ * upper one when two are equally near; the pitch unchanged when no
235
+ * transposition of it is available.
236
+ *
237
+ * @example
238
+ * ```ts
239
+ * import { BASS_4_STRING, foldIntoRange } from '@libraz/libcantus';
240
+ * foldIntoRange(27, BASS_4_STRING); // 39 — Eb1 is under the low E
241
+ * ```
242
+ * @category Core
243
+ */
244
+ declare function foldIntoRange(pitch: number, profile: InstrumentProfileLike): number;
245
+
246
+ /**
247
+ * Hierarchical seeds: one project number that addresses every part.
248
+ *
249
+ * A flat seed per generator makes the caller keep a table of numbers and,
250
+ * worse, makes "reroll the drums" mean "pick a number nobody else is using".
251
+ * Deriving instead — `deriveSeed(project, 'drums', 'chorus', 2)` — turns a
252
+ * reroll into an extra path segment, and every other part keeps the seed it
253
+ * had because its path did not change.
254
+ */
255
+ /**
256
+ * The address of one derivation: a namespace, and whatever names or indices
257
+ * locate the thing being seeded.
258
+ *
259
+ * Strings and numbers are kept apart by the hash, so `'3'` and `3` address
260
+ * different things, as do `['ab', 'c']` and `['a', 'bc']`.
261
+ *
262
+ * @category Utilities
263
+ */
264
+ type SeedPath = readonly (string | number)[];
265
+ /**
266
+ * Derive a child seed from a root seed and a path.
267
+ *
268
+ * The result is a 32-bit integer, so it can be passed straight to
269
+ * {@link createRng}. Derivation is a pure function of its arguments — the same
270
+ * root and path give the same seed in every runtime — and near-identical paths
271
+ * (`'drums'` against `'drum'`, bar 1 against bar 2) give unrelated seeds: the
272
+ * path is hashed with FNV-1a and finished with the MurmurHash3 fmix32
273
+ * avalanche step.
274
+ *
275
+ * @param root The project seed; an integer in 0..0xffffffff.
276
+ * @param path The address to derive at; string or finite number segments.
277
+ * @returns The derived seed, an integer in 0..0xffffffff.
278
+ * @throws If the root is not a 32-bit integer, or a segment is neither a
279
+ * string nor a finite number.
280
+ * @example
281
+ * ```ts
282
+ * import { createRng, deriveSeed } from '@libraz/libcantus';
283
+ * const drums = deriveSeed(42, 'drums', 'chorus', 3);
284
+ * const rng = createRng(drums); // rerolling only the drums: bump the 3
285
+ * ```
286
+ * @category Utilities
287
+ */
288
+ declare function deriveSeed(root: number, ...path: SeedPath): number;
289
+
290
+ /**
291
+ * Position-addressed randomness and threshold sampling.
292
+ *
293
+ * Drawing in call order makes a generator's output depend on how many draws
294
+ * preceded it, so editing a parameter in the middle of a piece redraws
295
+ * everything after it. Addressing each draw by where it happens — bar, beat,
296
+ * voice — removes that coupling: the value at a position depends on the
297
+ * position alone, so a change anywhere leaves every other position as it was.
298
+ *
299
+ * Deciding inclusion by comparing a fixed positional draw against a complexity
300
+ * dial gives the property a slider needs: raising the dial only adds events,
301
+ * and everything already sounding stays where it was.
302
+ */
303
+
304
+ /**
305
+ * A random source addressed by position rather than by call order.
306
+ *
307
+ * @category Utilities
308
+ */
309
+ type PositionalRng = {
310
+ /**
311
+ * The draw belonging to a position: a float in [0, 1) that depends only on
312
+ * the seed and the path, so it is the same however often and in whatever
313
+ * order it is asked for.
314
+ */
315
+ at: (...path: SeedPath) => number;
316
+ };
317
+ /**
318
+ * Create a position-addressed random source.
319
+ *
320
+ * `at` holds no cursor: it is a pure function of the seed and the path, safe to
321
+ * call in any order, any number of times, from anywhere in a generator. Its
322
+ * draws are independent of {@link deriveSeed} at the same path, so a generator
323
+ * may seed a sub-part and take a positional draw at one position without
324
+ * getting the same number twice.
325
+ *
326
+ * @param seed The seed; an integer in 0..0xffffffff, typically from
327
+ * {@link deriveSeed}.
328
+ * @returns The positional source.
329
+ * @throws If the seed is not a 32-bit integer.
330
+ * @example
331
+ * ```ts
332
+ * import { createPositionalRng, deriveSeed } from '@libraz/libcantus';
333
+ * const rng = createPositionalRng(deriveSeed(42, 'drums'));
334
+ * rng.at('ghost', 4, 2.5); // the same value however often it is asked for
335
+ * ```
336
+ * @category Utilities
337
+ */
338
+ declare function createPositionalRng(seed: number): PositionalRng;
339
+ /**
340
+ * Whether the event at a position belongs in the output at a given complexity.
341
+ *
342
+ * The test is `at(...path) < complexity`, and because the draw is fixed by the
343
+ * position, the selected set grows monotonically with complexity: for any
344
+ * `c1 < c2` the events at `c1` are a subset of the events at `c2` over the same
345
+ * seed and the same path space. Complexity 0 selects nothing and complexity 1
346
+ * selects everything.
347
+ *
348
+ * @param rng The positional source; may be a caller-supplied one.
349
+ * @param complexity The dial, in [0, 1].
350
+ * @param path The position to test.
351
+ * @returns True when the position is included.
352
+ * @throws If the complexity is outside [0, 1], or the source returns a value
353
+ * outside [0, 1).
354
+ * @example
355
+ * ```ts
356
+ * import { createPositionalRng, includeAt } from '@libraz/libcantus';
357
+ * const rng = createPositionalRng(7);
358
+ * includeAt(rng, 0.3, 'ghost', 4, 2.5); // raising 0.3 only adds hits
359
+ * ```
360
+ * @category Utilities
361
+ */
362
+ declare function includeAt(rng: PositionalRng, complexity: number, ...path: SeedPath): boolean;
363
+
364
+ export { LIMBS as L, canSound as i, createPositionalRng as j, deriveSeed as k, fingeringsFor as l, foldIntoRange as m, includeAt as n, instrumentRange as o, toStringedProfile as p, toInstrumentProfile as t };
365
+ export type { InstrumentProfile as I, PercussionProfile as P, SeedPath as S, ValidatedPercussionProfile as V, InstrumentProfileCommon as a, InstrumentProfileLike as b, Limb as c, PositionalRng as d, StringFingering as e, StringedProfile as f, ValidatedProfile as g, ValidatedStringedProfile as h };