@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,808 @@
1
+ import { b as MeterLike } from '../index-Bf0Sv8a9.js';
2
+ export { M as MeterChange, c as MeterMap, T as TimeSignature } from '../index-Bf0Sv8a9.js';
3
+ import { h as NoteEvent, a as Articulation, b as IntervalLike } from '../index-C9MYbuKS.js';
4
+ export { I as IntervalData, c as IntervalQualityLabel, e as KeyScale, g as NoteData, S as SpelledInterval } from '../index-C9MYbuKS.js';
5
+ import { e as ChordSegment, c as ChordLike, K as KeyLike } from '../coerce-CUhHc3Tu.js';
6
+ export { b as ChordData, d as ChordQuality, g as ChordSpan, i as ChordToneRole, k as KeyVariant, l as PitchSpelling, m as ProfileWeights, n as ResolvedKey, r as SpelledKeyLike, s as SpelledKeyScale } from '../coerce-CUhHc3Tu.js';
7
+ import { h as ChordTimeline } from '../types-7mGFwvMm.js';
8
+ export { B as BarPositionProfile, b as BorrowedSource, e as CadenceType, F as FormSection, o as HarmonicFunction, v as MelodicContourShape, y as MotifGraph, z as MotifGraphEdge, G as MotifGraphNode, P as MotifRelationSummary, X as ReductionLevel, Y as ReferenceCadence, Z as ReferenceChord, _ as ReferenceForm, $ as ReferenceHarmony, a0 as ReferenceKeyRegion, a1 as ReferenceMelody, a2 as ReferenceMotif, a3 as ReferencePhrase, a4 as ReferencePhraseMelody, a5 as ReferenceProfile, a7 as RhythmAnalysis } from '../types-7mGFwvMm.js';
9
+ import { f as StringedProfile, P as PercussionProfile, c as Limb } from '../positional-DLnfUgqG.js';
10
+ export { I as InstrumentProfile, a as InstrumentProfileCommon, d as PositionalRng, S as SeedPath } from '../positional-DLnfUgqG.js';
11
+ export { H as HarmonyRole } from '../index-C7KCaTRz.js';
12
+ import { x as Genre, w as GenerationContextInput, ah as Vocabulary, y as GridEvent, r as DrumStyle, ac as Section, s as DrumVoice, z as GrooveFeel, p as DrumHit, I as HarmonizeOptions, K as HarmonizeResult, j as CompositionPlan } from '../index-jgeug9EA.js';
13
+ export { B as BAR_STEPS, a as BASS_STYLES, b as BEAT_STEPS, c as BORROWED_DEGREES, d as BassLineOptions, e as BassSegment, f as BassStyle, g as BorrowedChord, C as COMPOSITION_PLAN_VERSION, h as Complexity, i as CompositionEvaluation, k as CompositionPlanOptions, l as CompositionViolation, m as CounterMelodyOptions, D as DRUM_NOTES, n as DeformOptions, o as Draw, q as DrumRole, t as DrumsOptions, E as EuclideanKick, u as EvaluateCompositionOptions, G as GENRES, v as GenerationContext, A as GrooveSlot, F as GrooveStyle, H as GrooveTemplate, J as HarmonizePlacement, L as HumanizeOptions, M as MelodyNote, N as MelodyOptions, O as MotifCell, P as MotifContour, Q as MotifNote, R as MotifOptions, S as MotifTransform, T as ORNAMENT_STYLES, U as OrnamentOptions, V as OrnamentStyle, W as PROVENANCE_BASES, X as PlannedChord, Y as PlannedMotif, Z as PlannedPhrase, _ as PlannedRhythm, $ as PlannedSection, a0 as PreserveWeights, a1 as ProgFunction, a2 as ProgStyle, a3 as ProgressionDegree, a4 as ProgressionOptions, a5 as ProgressionPreset, a6 as Provenance, a7 as ProvenanceBasis, a8 as ResolvedContext, a9 as RhythmEvent, aa as RhythmOptions, ab as STEP_BEATS, ad as SubstituteOptions, ae as Substitution, af as SubstitutionType, ag as SyncopateOptions, ai as VocabularyQuery, aj as applyGrooveTemplate, ak as assertVocabulary, al as deform, am as deriveCompositionPlan, an as developMotif, ao as double, ap as doubleTime, aq as drumVoiceOf, ar as evaluateComposition, as as extractGrooveTemplate, at as fitsQuery, au as generateBassLine, av as generateCounterMelody, aw as generateDrums, ax as generateMelody, ay as generateMotif, az as generateProgression, aA as generateRhythm, aB as gridMetricWeight, aC as halfTime, aD as humanize, aE as mergeVocabulary, aF as modalInterchangePalette, aG as motifToNoteEvents, aH as negativeHarmonyMirror, aI as onsetWeightCurve, aJ as ornament, aK as ornamentBy, aL as pickProgressionPreset, aM as pickVocabulary, aN as progressions, aO as progressionsByStyle, aP as resolveContext, aQ as rhythmDensity, aR as rhythmToNoteEvents, aS as selectVocabulary, aT as substituteChord, aU as syncopate, aV as thin, aW as transformMotif, aX as vocabularyOfKind, aY as withinCeiling } from '../index-jgeug9EA.js';
14
+
15
+ /**
16
+ * The playing-difficulty ceiling, as the generators apply it.
17
+ *
18
+ * A ceiling is not an intensity: a passage can be harmonically involved and
19
+ * easy to play, or plain and hard. So difficulty never proposes material — it
20
+ * only rejects what the other complexity dials proposed, and only on the
21
+ * timing layer, where speed is what stands in the way. Whether the note exists
22
+ * on the instrument at all, and whether the hand can hold the shape, belong to
23
+ * the instrument profile and hold regardless of the ceiling.
24
+ */
25
+ /** The ceiling's lowest level: what a beginner sustains. */
26
+ declare const MIN_DIFFICULTY = 1;
27
+ /** The ceiling's highest level: what a rudimental player sustains. */
28
+ declare const MAX_DIFFICULTY = 5;
29
+ /**
30
+ * Whether a player at this ceiling keeps up a stream of strokes on one voice.
31
+ *
32
+ * @param stepBeats Gap between consecutive strokes, in quarter-note beats.
33
+ * @param bpm Tempo, or undefined when the caller gave none.
34
+ * @param difficulty The ceiling, or undefined for no ceiling.
35
+ * @returns True when the stream is inside the ceiling, and whenever either the
36
+ * ceiling or the tempo is unknown — a limit nobody stated constrains nothing.
37
+ */
38
+ declare function sustainsStrokes(stepBeats: number, bpm: number | undefined, difficulty: number | undefined): boolean;
39
+ /**
40
+ * Whether the fretting hand covers a leap in the time available.
41
+ *
42
+ * @param semitones Distance moved; on a fretted neck one fret is one semitone.
43
+ * @param stepBeats Time to move it in, in quarter-note beats.
44
+ * @param bpm Tempo, or undefined when the caller gave none.
45
+ * @param difficulty The ceiling, or undefined for no ceiling.
46
+ * @returns True when the shift is inside the ceiling, and whenever either the
47
+ * ceiling or the tempo is unknown.
48
+ */
49
+ declare function sustainsShift(semitones: number, stepBeats: number, bpm: number | undefined, difficulty: number | undefined): boolean;
50
+
51
+ /**
52
+ * Lay the figures of the dictionary over a chord progression.
53
+ *
54
+ * A segment takes a figure its genre plays, chosen by a draw addressed to that
55
+ * segment, and the figure's degrees are read against the chord sounding under
56
+ * it. What the figures are is `licks-data.ts`; which pitch a degree asks for is
57
+ * `degrees.ts`. This module is what places them: which segment takes one, how
58
+ * it is fitted to the span, and how one figure leads into the next.
59
+ */
60
+
61
+ /**
62
+ * Options controlling {@link placeLicks}.
63
+ *
64
+ * @category Composition
65
+ */
66
+ type PlaceLicksOptions = {
67
+ /**
68
+ * The genre whose figures may be used. Genre is what selects the material:
69
+ * the dials then deform it, and the ceiling rejects it.
70
+ */
71
+ genre: Genre;
72
+ /**
73
+ * The hardest figure that may be used, 1 to 5. Sugar for
74
+ * `ctx: { complexity: { difficulty } }`; the context wins over both.
75
+ */
76
+ difficulty?: number;
77
+ /** Time signature, in any form that names one; defaults to 4/4. */
78
+ ts?: MeterLike;
79
+ /**
80
+ * Target register as a base MIDI octave; roots land around `octave*12+12`.
81
+ *
82
+ * @defaultValue 2
83
+ */
84
+ octave?: number;
85
+ /** The instrument the line is written for; its range always applies. */
86
+ instrument?: StringedProfile;
87
+ /**
88
+ * The generation context. Its `vocabulary` brings the caller's own figures,
89
+ * its `complexity.ornament` decides how much decoration survives, and its
90
+ * `complexity.difficulty` is the ceiling figures are rejected against.
91
+ *
92
+ * Its `complexity.rhythmic` is how busy the line is, in [0, 1]: it decides
93
+ * both how often a segment takes a figure at all and, above its middle
94
+ * setting, how much the figure is syncopated — one dial, because "less busy"
95
+ * means both. Its `bpm` is the tempo the ceiling is measured against, and its
96
+ * `seed` fixes which figures are chosen and where they land.
97
+ *
98
+ * @defaultValue `{ seed: 0, bpm: 120, complexity: { rhythmic: 0.6 } }`
99
+ */
100
+ ctx?: GenerationContextInput;
101
+ /**
102
+ * Maximum number of segments {@link placeLicks} may lay figures over, and of
103
+ * bars those segments span. One figure is placed per bar of a segment, so
104
+ * both are counted: this is the guard against an unbounded caller — a segment
105
+ * running to a beat far past the music — rather than a limit on any search.
106
+ *
107
+ * @defaultValue 1000000
108
+ */
109
+ budget?: number;
110
+ };
111
+ /**
112
+ * Lay licks over a chord placement.
113
+ *
114
+ * Each segment is offered the figures whose conditions it meets — the genre,
115
+ * the chord quality, the tempo, and the difficulty ceiling — and one of them is
116
+ * chosen by a draw addressed to that segment, so changing a chord elsewhere
117
+ * leaves this segment's figure where it was. A segment that takes no figure
118
+ * gets its root, and the last note before a chord change leads into the next
119
+ * root by step, the way a walking line does.
120
+ *
121
+ * @param timeline Chord segments to play over; they need not be pre-sorted, and
122
+ * each segment's chord may be written as a chord symbol.
123
+ * @param key Key context, which answers for the degrees the chords do not; a
124
+ * key name such as `'C major'` is read as that key.
125
+ * @param opts Genre, density, ceiling and seed.
126
+ * @returns Bass notes sorted by onset, non-overlapping.
127
+ * @throws If a segment has a non-positive duration, two segments overlap, or
128
+ * the genre is not one this library names. A bass part is monophonic, so
129
+ * overlapping segments are refused here exactly as {@link generateBassLine}
130
+ * refuses them rather than being laid over each other.
131
+ *
132
+ * @example
133
+ * ```ts
134
+ * import { majorKey, makeChord, placeLicks } from '@libraz/libcantus';
135
+ * const timeline = [
136
+ * { startBeat: 0, endBeat: 4, chord: makeChord(0, 'maj7') },
137
+ * { startBeat: 4, endBeat: 8, chord: makeChord(5, 'maj7') },
138
+ * ];
139
+ * const notes = placeLicks(timeline, majorKey(0), { genre: 'motown', ctx: { seed: 7 } });
140
+ * ```
141
+ *
142
+ * @category Composition
143
+ */
144
+ declare function placeLicks(timeline: readonly (Omit<ChordSegment, 'chord'> & {
145
+ chord: ChordLike;
146
+ })[], key: KeyLike, opts: PlaceLicksOptions): NoteEvent[];
147
+
148
+ /**
149
+ * The bass lick dictionary: the figures a bass player reaches for, held as
150
+ * chord-relative degrees and beat positions and deformed to fit the progression
151
+ * actually in front of them.
152
+ *
153
+ * Provenance: no entry reproduces a bass line from a particular song. Each is a
154
+ * figure that belongs to nobody — the descending soul walk-down, the octave
155
+ * slap, the boogie shuffle — of the kind every player of that music already
156
+ * plays, and each records the ground it qualifies under.
157
+ */
158
+
159
+ /**
160
+ * One note of a lick, relative to the chord it is played over.
161
+ *
162
+ * A degree is 1-based and counts up from the chord's root: 1 is the root, 3 the
163
+ * third, 8 the octave. Degrees the chord itself names — the third, fifth and
164
+ * seventh — are taken from the chord, so the same figure comes out major over a
165
+ * major chord and minor over a minor one. A degree the chord's quality settles
166
+ * without stating it follows the quality: the third of a suspended chord is the
167
+ * tone the suspension put there, and a seventh chord's remaining degrees are
168
+ * its own chord scale's. Only what the harmony leaves open is taken from the
169
+ * key. That is what lets a figure be written once and fit a whole progression.
170
+ *
171
+ * @category Composition
172
+ */
173
+ type LickNote = GridEvent & {
174
+ /** Chord degree, 1-based; 8 is the octave above the root. */
175
+ degree: number;
176
+ /** Chromatic alteration in semitones, for a flattened or raised degree. */
177
+ alter?: number;
178
+ /**
179
+ * Sounding length in sixteenths. Absent, the note sounds to the next onset,
180
+ * as a line written by {@link generateBassLine} does: the built-in figures
181
+ * name no length, so a figure is legato unless it says otherwise.
182
+ */
183
+ lengthSteps?: number;
184
+ /** How the note is played, when it is more than a plain note. */
185
+ articulation?: Articulation;
186
+ };
187
+ /**
188
+ * A lick: its notes and how long the whole figure lasts.
189
+ *
190
+ * @category Composition
191
+ */
192
+ type LickMaterial = {
193
+ /** Length of the figure in sixteenths. */
194
+ lengthSteps: number;
195
+ notes: LickNote[];
196
+ };
197
+ /**
198
+ * A lick with the conditions it fits.
199
+ *
200
+ * @category Composition
201
+ */
202
+ type BassLick = Vocabulary<LickMaterial>;
203
+ /**
204
+ * Whether a caller's material is a bass lick.
205
+ *
206
+ * @category Composition
207
+ */
208
+ declare function isLickMaterial(material: unknown): material is LickMaterial;
209
+ /**
210
+ * The built-in bass licks, in declaration order.
211
+ *
212
+ * @category Composition
213
+ */
214
+ declare const BASS_LICKS: readonly BassLick[];
215
+
216
+ /**
217
+ * Imitative entries: a second voice restating what the first has just sung.
218
+ *
219
+ * A motif transform has no time relationship to anything — it returns a cell,
220
+ * and where that cell goes is the caller's problem. An imitation is defined by
221
+ * that relationship: it enters at a stated beat, at a stated interval, against a
222
+ * voice that is still sounding. That is what a canon is, and what the answering
223
+ * phrase in the second half of a chorus is.
224
+ */
225
+
226
+ /** Every way an imitation can answer, in declaration order. */
227
+ declare const IMITATION_ANSWERS: readonly ["real", "tonal"];
228
+ /**
229
+ * How an imitation answers the voice it follows.
230
+ *
231
+ * A `real` answer transposes literally, keeping every interval of the subject
232
+ * and leaving the key where the interval puts it. A `tonal` answer counts scale
233
+ * degrees instead, so the answer stays in the key: every interval keeps the
234
+ * number of degrees it spanned in the subject, and only its quality changes as
235
+ * the key's own pattern of steps and half steps asks — a major third answered by
236
+ * a minor one.
237
+ *
238
+ * @category Composition
239
+ */
240
+ type ImitationAnswer = (typeof IMITATION_ANSWERS)[number];
241
+ /**
242
+ * Options controlling {@link imitate}.
243
+ *
244
+ * @category Composition
245
+ */
246
+ type ImitationOptions = {
247
+ /**
248
+ * Beat at which the imitation enters; the copied material starts here.
249
+ * Negative like any other onset, for an answer that enters in a pickup.
250
+ */
251
+ atBeat: number;
252
+ /**
253
+ * Interval to imitate at, spelled: `'P5'` for an answer a fifth above,
254
+ * `'-P4'` for one a fourth below.
255
+ */
256
+ interval: IntervalLike;
257
+ /**
258
+ * The key the answer is measured in; what makes a tonal answer tonal. A key
259
+ * name such as `'C major'` is read as that key.
260
+ */
261
+ key: KeyLike;
262
+ /**
263
+ * Whether the answer transposes literally or by scale degree.
264
+ *
265
+ * @defaultValue 'real'
266
+ */
267
+ answer?: ImitationAnswer;
268
+ /**
269
+ * Turn the subject upside down before transposing it, mirroring it about its
270
+ * own first note: by semitone for a real answer, by scale degree for a tonal
271
+ * one.
272
+ *
273
+ * @defaultValue false
274
+ */
275
+ invert?: boolean;
276
+ /** First beat of the lead to imitate; defaults to the start of the line. */
277
+ from?: number;
278
+ /** Beat to imitate up to, exclusive; defaults to the end of the line. */
279
+ to?: number;
280
+ /**
281
+ * Factor applied to the copied velocities, for an answer that sits under the
282
+ * voice it follows.
283
+ *
284
+ * @defaultValue 1
285
+ */
286
+ velocityScale?: number;
287
+ };
288
+ /**
289
+ * Answer a leading voice with an imitation of it.
290
+ *
291
+ * The chosen span of the lead is copied so that its first note falls on
292
+ * `atBeat`, keeping its internal rhythm; only the answer is returned, so the
293
+ * caller decides what to do with the two voices together. Pitches move by
294
+ * `interval`: literally for a real answer, by scale degree for a tonal one, and
295
+ * upside down first when `invert` is set. Inversion mirrors about the first note
296
+ * of the copied span, so the answer starts where the transposition puts that
297
+ * note either way, whether or not it is in the key. In a tonal answer a pitch
298
+ * outside the key keeps its distance
299
+ * from the scale tone below it, and inversion mirrors that distance too — a
300
+ * chromatic passing note stays a chromatic passing note, on the other side.
301
+ * Where a mirrored chromatic note falls into a diatonic semitone the key leaves
302
+ * it no room, and it lands on the scale tone there, so a subject saturated with
303
+ * chromatic steps can answer with a pitch repeated.
304
+ *
305
+ * @param lead The voice being imitated, in ascending onset order.
306
+ * @param opts Where the answer enters, at what interval, and in what key.
307
+ * @returns The imitation as note events sorted by onset; `[]` when the chosen
308
+ * span holds no sounding notes. Notes with a zero or negative duration never
309
+ * sound and are not copied, so the answer can be shorter than the span. Every
310
+ * other field of a copied note — its articulation, and its velocity through
311
+ * `velocityScale` — comes across with it.
312
+ * @throws If the span is reversed, the answer is not a known kind, or a
313
+ * transposed pitch leaves the MIDI range.
314
+ * @example
315
+ * ```ts
316
+ * import { imitate, majorKey } from '@libraz/libcantus';
317
+ * const lead = [0, 1, 2].map((beat) => ({ pitch: 60 + beat, startBeat: beat, durationBeat: 1 }));
318
+ * imitate(lead, { atBeat: 2, interval: 'P5', key: majorKey(0) });
319
+ * // the same three notes a fifth up, entering at beat 2
320
+ * ```
321
+ * @category Composition
322
+ */
323
+ declare function imitate(lead: readonly NoteEvent[], opts: ImitationOptions): NoteEvent[];
324
+
325
+ /**
326
+ * The fill vocabulary, as data.
327
+ *
328
+ * Every archetype is a list of strokes on the bar's grid and every selection is
329
+ * a table indexed by a draw, so a fill can be added, replaced, or supplied by a
330
+ * caller without touching a generator. The generator's part is to look one up.
331
+ */
332
+
333
+ /** The thirteen fill archetypes for section transitions, in declaration order. */
334
+ declare const FILL_TYPES: readonly ["snareRoll", "tomDescend", "tomAscend", "snareTomCombo", "simpleCrash", "linearFill", "ghostToAccent", "bdSnareAlternate", "hiHatChoke", "tomShuffle", "breakdownFill", "flamsAndDrags", "halfTimeFill"];
335
+ /** The thirteen fill archetypes for section transitions. */
336
+ type FillType = (typeof FILL_TYPES)[number];
337
+ /** The bases a fill stroke's velocity is read against, in declaration order. */
338
+ declare const FILL_VELOCITY_BASES: readonly ["fill", "accent"];
339
+ /**
340
+ * How loud one stroke of a fill is.
341
+ *
342
+ * A fill's dynamics are written against the fill's own base velocity rather
343
+ * than in absolute terms, so the same archetype sounds right in a verse and a
344
+ * chorus: `fill` is the body of the fill, `accent` the stroke that lands. One
345
+ * base for the whole gesture, not one per beat — a crescendo that restarts its
346
+ * arithmetic at every beat line falls back in the middle of itself.
347
+ */
348
+ type FillVelocity = {
349
+ base: (typeof FILL_VELOCITY_BASES)[number];
350
+ /** Factor on the base, for a crescendo or a ghosted stroke. */
351
+ scale?: number;
352
+ /** Fixed offset in MIDI velocity, for a stroke a little above or below. */
353
+ offset?: number;
354
+ };
355
+ /** One stroke of a fill, positioned within the beat it belongs to. */
356
+ type FillStroke = {
357
+ /** General MIDI note number of the voice struck. */
358
+ voice: number;
359
+ /** Offset from the start of the beat, in quarter-note beats. */
360
+ offset: number;
361
+ /** Sounding length, in quarter-note beats. */
362
+ duration: number;
363
+ velocity: FillVelocity;
364
+ /** How the stroke is played, when it is more than a plain hit. */
365
+ articulation?: Articulation;
366
+ };
367
+ /**
368
+ * A fill archetype: what each beat of the fill bar plays.
369
+ *
370
+ * Beats are indexed from the start of the bar. A beat with no entry is silent,
371
+ * which is how the sparse archetypes leave the earlier beats to the groove.
372
+ */
373
+ type FillArchetype = {
374
+ /** Strokes per beat of the bar, indexed 0..3. */
375
+ atBeat: readonly (readonly FillStroke[])[];
376
+ /**
377
+ * Whether the archetype stops where its own strokes stop, rather than holding
378
+ * its last beat over the beats of the bar it does not write.
379
+ *
380
+ * It answers for an archetype shorter than the bar it is placed in, so the
381
+ * built-in archetypes — written beat by beat against the four-beat bar
382
+ * {@link generateDrums} accepts — are unaffected by it; a caller's archetype
383
+ * that writes fewer beats is where it decides anything. Most figures read
384
+ * naturally when held, but a half-time gesture is bar-long and stops there.
385
+ */
386
+ boundToBar?: boolean;
387
+ };
388
+ /**
389
+ * The fill dictionary.
390
+ *
391
+ * Provenance: every archetype here is a rudiment or a stock phrase-end gesture
392
+ * — a snare crescendo, a descending tom run, a crash on the last off-beat — of
393
+ * the kind every drummer plays and nobody owns. None reproduces a fill from a
394
+ * particular recording.
395
+ */
396
+ declare const FILL_ARCHETYPES: Readonly<Record<FillType, FillArchetype>>;
397
+ /**
398
+ * Whether a caller's material is a fill.
399
+ *
400
+ * A context carries one dictionary for the whole piece, so each generator has
401
+ * to recognise its own material; a bass lick reaching the fill selector would
402
+ * otherwise be rendered as silence.
403
+ */
404
+ declare function isFillArchetype(material: unknown): material is FillArchetype;
405
+
406
+ /**
407
+ * The kick vocabulary, as data on a sixteenth grid.
408
+ *
409
+ * The grid is sixteenths rather than eighths because most of what belongs in a
410
+ * kick dictionary cannot be written on eighths at all: the funk and modern-pop
411
+ * basics live on the sixteenths between the beats. The eighth-note patterns map
412
+ * onto the even steps of the same grid, so they read exactly as before.
413
+ */
414
+
415
+ /** Sixteenth steps in one bar of 4/4; the grid a kick pattern is written on. */
416
+ declare const KICK_STEPS = 16;
417
+ /**
418
+ * Kick presence flags across the sixteen 16th-note slots of a bar.
419
+ *
420
+ * Index `n` is the `n`-th sixteenth from the downbeat, so beat 3 is index 8 and
421
+ * the "and" of 2 is index 6.
422
+ */
423
+ type KickPattern = readonly boolean[];
424
+ /**
425
+ * One onset of a kick figure.
426
+ *
427
+ * A slot with no probability is part of the figure itself and always sounds.
428
+ * One with a probability is where the rhythmic dial reaches the kick: the draw
429
+ * is fixed by position and leaned on by the dial, so raising the dial fills
430
+ * slots in without emptying any that were already there.
431
+ */
432
+ type KickSlot = {
433
+ /** Sixteenth index within the bar, 0..15. */
434
+ step: number;
435
+ /** Chance the slot is taken before the dial leans on it. */
436
+ probability?: number;
437
+ /** Draw address for the slot; slots that may sound must name one. */
438
+ slot?: string;
439
+ /** Restrict the slot to bars of one parity, for a two-bar figure. */
440
+ barParity?: 0 | 1;
441
+ /** Sections the slot is added in; absent means every section. */
442
+ sections?: Section[];
443
+ };
444
+ /** A style's kick figure: the slots it always plays, plus the ones it may. */
445
+ type KickFigure = readonly KickSlot[];
446
+ /**
447
+ * The kick dictionary, keyed by internal style.
448
+ *
449
+ * Provenance: each figure is the plain pulse of its style — the four-on-the-
450
+ * floor dance kick, the backbeat-answering "and" of two, the clave-leaning
451
+ * latin figure — none of them traceable to a particular record.
452
+ */
453
+ declare const KICK_FIGURES: Readonly<Record<DrumStyle, KickFigure>>;
454
+
455
+ /**
456
+ * A drum kit played with four limbs, covering every voice
457
+ * {@link generateDrums} emits.
458
+ *
459
+ * A kit is bounded by limbs rather than by range: two voices wanting the same
460
+ * hand at the same instant is what makes a pattern unplayable, and a voice no
461
+ * limb reaches is not on the kit at all.
462
+ *
463
+ * The auxiliary percussion — hand-claps, tambourine, shaker — is dubbed over
464
+ * the kit on a pass of its own, so it sounds through a backbeat whose snare and
465
+ * hi-hat already take both hands, and the four limbs stay the bound on the
466
+ * groove itself.
467
+ *
468
+ * @example
469
+ * ```ts
470
+ * import { DRUM_KIT, generateDrums, playability } from '@libraz/libcantus';
471
+ * const hits = generateDrums({
472
+ * bars: 1,
473
+ * style: 'funk',
474
+ * section: 'chorus',
475
+ * ctx: { bpm: 120, complexity: { rhythmic: 0.8 } },
476
+ * });
477
+ * const report = playability(hits, DRUM_KIT, 120);
478
+ * ```
479
+ * @category Composition
480
+ */
481
+ declare const DRUM_KIT: PercussionProfile;
482
+
483
+ /**
484
+ * The drum pattern dictionary: the bar-long figures that make a groove belong
485
+ * to a genre rather than merely being correct.
486
+ *
487
+ * Provenance: every pattern here is the plain, unattributable pulse of its
488
+ * genre — the figure taught as "this is how that music goes" — written out on
489
+ * the sixteenth grid from that description. None reproduces the drum part of a
490
+ * particular recording, and each entry says which ground it qualifies under.
491
+ */
492
+
493
+ /**
494
+ * One stroke of a pattern, on the bar's sixteenth grid.
495
+ *
496
+ * Velocity is a factor of the passage's base velocity rather than a MIDI
497
+ * number, so the same figure sits right in a verse and in a chorus.
498
+ */
499
+ type DrumStroke = GridEvent & {
500
+ voice: DrumVoice;
501
+ /** Sounding length in quarter-note beats; one sixteenth when absent. */
502
+ duration?: number;
503
+ articulation?: Articulation;
504
+ /** Which limb plays the stroke, where the figure depends on it. */
505
+ limb?: Limb;
506
+ };
507
+ /**
508
+ * A bar-long drum figure.
509
+ *
510
+ * @category Composition
511
+ */
512
+ type DrumPattern = {
513
+ /** Sixteenth steps in the figure; a 4/4 bar is sixteen. */
514
+ steps: number;
515
+ strokes: DrumStroke[];
516
+ };
517
+ /**
518
+ * A drum figure with the conditions it fits.
519
+ *
520
+ * @category Composition
521
+ */
522
+ type DrumVocabulary = Vocabulary<DrumPattern>;
523
+ /**
524
+ * Whether a caller's material is a drum pattern.
525
+ *
526
+ * A context carries one dictionary for the whole piece, so each generator
527
+ * recognises its own material: an entry meant for the bass is invisible here
528
+ * rather than mis-read.
529
+ *
530
+ * @category Composition
531
+ */
532
+ declare function isDrumPattern(material: unknown): material is DrumPattern;
533
+ /**
534
+ * The built-in drum patterns, in declaration order.
535
+ *
536
+ * @category Composition
537
+ */
538
+ declare const DRUM_PATTERNS: readonly DrumVocabulary[];
539
+ /**
540
+ * Options controlling {@link placeDrumPattern}.
541
+ *
542
+ * @category Composition
543
+ */
544
+ type DrumPatternOptions = {
545
+ /** Number of bars to generate. */
546
+ bars: number;
547
+ /**
548
+ * The genre whose figures may be used. Genre is what selects the material;
549
+ * the complexity dials then deform it and the difficulty ceiling rejects it.
550
+ */
551
+ genre: Genre;
552
+ /** Section the pattern plays in, matched against each entry's own sections. */
553
+ section?: Section;
554
+ /** Time signature, in any form that names one; defaults to 4/4. */
555
+ ts?: MeterLike;
556
+ /**
557
+ * The generation context. `bpm` is the tempo, `complexity.rhythmic` thins the
558
+ * figure below its middle setting and syncopates it above,
559
+ * `complexity.ornament` decides how many ghosts survive,
560
+ * `complexity.difficulty` rejects a figure the player could not keep up at
561
+ * this tempo, `vocabulary` brings figures of the caller's own, and `seed`
562
+ * fixes which figure is chosen for each bar.
563
+ *
564
+ * @defaultValue `{ seed: 0, bpm: 120 }`
565
+ */
566
+ ctx?: GenerationContextInput;
567
+ /**
568
+ * Play the figure at half or double its written rate. This is a deformation
569
+ * like the dials, not a different figure: the dictionary entry is the same.
570
+ *
571
+ * It is named for the note values it changes because `feel` names the swing
572
+ * the figure is played with, here and in {@link generateDrums} alike.
573
+ *
574
+ * @defaultValue `'straight'`
575
+ */
576
+ rate?: 'straight' | 'half' | 'double';
577
+ /**
578
+ * The swing the figure is played with. Some entries are written on the
579
+ * straight grid and are only themselves once a triplet feel is applied at
580
+ * render — the half-time shuffle is the plain case — so this is the surface
581
+ * those entries name when they say the feel comes from the performance.
582
+ *
583
+ * @defaultValue `'straight'`
584
+ */
585
+ feel?: GrooveFeel;
586
+ /** Base velocity the figure's own factors are read against. */
587
+ velocity?: number;
588
+ /**
589
+ * Maximum number of onsets {@link placeDrumPattern} may write. One figure is
590
+ * placed per bar, so this is the guard against an unbounded caller rather
591
+ * than a limit on any search.
592
+ *
593
+ * @defaultValue 1000000
594
+ */
595
+ budget?: number;
596
+ };
597
+ /**
598
+ * Generate a genre-characteristic groove from the pattern dictionary.
599
+ *
600
+ * The three dials never fight, because each owns a different step: the genre
601
+ * chooses which figures are candidates, the complexity dials deform the chosen
602
+ * figure, and the difficulty ceiling rejects a figure whose closest pair of
603
+ * strokes is faster than a player at that ceiling sustains. A rejected figure
604
+ * is dropped from the candidates rather than simplified, since a simplified
605
+ * figure is a different figure.
606
+ *
607
+ * @param opts Generation options.
608
+ * @returns Percussion onsets in onset order, ties broken by pitch.
609
+ * @throws If the bar count, tempo, or time signature is invalid, or the genre
610
+ * is not one this library names.
611
+ *
612
+ * @example
613
+ * ```ts
614
+ * import { placeDrumPattern } from '@libraz/libcantus';
615
+ * const hits = placeDrumPattern({ bars: 2, genre: 'bossa', ctx: { seed: 7, bpm: 130 } });
616
+ * ```
617
+ *
618
+ * @category Composition
619
+ */
620
+ declare function placeDrumPattern(opts: DrumPatternOptions): DrumHit[];
621
+
622
+ /**
623
+ * What a melody note contributes to the harmony: either a structural tone the
624
+ * chord has to account for, or the ornament figure that explains it away.
625
+ *
626
+ * @category Reharmonization
627
+ */
628
+ type MelodyToneRole = 'structural' | 'passing' | 'neighbor' | 'appoggiatura' | 'suspension' | 'anticipation' | 'escape';
629
+ /**
630
+ * One melody note's classification: its index in the classified melody, the
631
+ * figure it forms, and whether that figure makes it ornamental.
632
+ *
633
+ * @category Reharmonization
634
+ */
635
+ type ClassifiedMelodyTone = {
636
+ noteIndex: number;
637
+ role: MelodyToneRole;
638
+ /** True for every role but `'structural'`. */
639
+ ornamental: boolean;
640
+ };
641
+ /**
642
+ * Classify a melody's ornaments from the melody and the metre alone.
643
+ *
644
+ * This is deliberately chord-free: a harmonizer needs to know which notes the
645
+ * chords must explain *before* it can choose them, so nothing here may consult a
646
+ * harmony. What remains is the melodic and metric evidence — stepwise approach
647
+ * and departure, repeated pitches, leaps, and the relative metric weight and
648
+ * length of a note against its neighbours.
649
+ *
650
+ * The figures are recognized in the order suspension, passing, neighbor,
651
+ * anticipation, appoggiatura, escape. A note is judged ornamental only when it
652
+ * is metrically and rhythmically subordinate to the neighbours that frame it
653
+ * (or, for the accented figures, when it leans on a stronger beat than its
654
+ * approach and gives way to a resolution). A note without an adjacent
655
+ * predecessor and successor has no figure to belong to and stays structural, so
656
+ * the first and last notes of a phrase are always structural.
657
+ *
658
+ * The notes are read in onset order, ties by pitch, whatever order they are
659
+ * listed in. A note of zero length sounds nothing: it is structural and is no
660
+ * other note's neighbour.
661
+ *
662
+ * @param melody The melody, in any order.
663
+ * @param ts Time signature used to weight metric accents.
664
+ * @returns One classification per input note, in input order.
665
+ * @example
666
+ * ```ts
667
+ * import { classifyMelodyTones } from '@libraz/libcantus';
668
+ * const melody = [60, 62, 64, 60].map((pitch, i) => ({
669
+ * pitch,
670
+ * startBeat: i,
671
+ * durationBeat: 1,
672
+ * }));
673
+ * classifyMelodyTones(melody, { numerator: 4, denominator: 4 })[1];
674
+ * // { noteIndex: 1, role: 'passing', ornamental: true }
675
+ * ```
676
+ * @category Reharmonization
677
+ */
678
+ declare function classifyMelodyTones(melody: readonly NoteEvent[], ts: MeterLike): ClassifiedMelodyTone[];
679
+
680
+ /**
681
+ * Harmonize a melody with a min-cost chord progression.
682
+ *
683
+ * The melody's ornaments are classified first, from the melody and the metre
684
+ * alone (see {@link classifyMelodyTones}); the chords then have to explain the
685
+ * structural tones only, so a passing tone no longer buys itself a chord. The
686
+ * melody is segmented by `harmonicRhythm`; each segment is scored against the
687
+ * candidate chords the harmonic dial opens — the key's own triads, then the
688
+ * secondary dominants, then the parallel mode's chords, one at a time as
689
+ * `ctx.complexity.harmonic` rises from 0 to 1 — by the fit of those structural
690
+ * tones, and a Viterbi search picks the lowest-cost path using a
691
+ * functional-flow transition cost and a cadence bonus at the end of the melody
692
+ * it is given — one cadence, at the close, unless `phraseEnds` names the closes
693
+ * inside a longer line, and then one at each of them as well. Runs of the same
694
+ * chord are reported once, so the chord count follows the harmony rather than
695
+ * the grid.
696
+ *
697
+ * With `placement.transposeSearch` the melody is moved into the key it is
698
+ * harmonized in, and `transposeSemitones` reports how far: the shifts that
699
+ * leave the fewest beats of the melody outside the key are kept, and the
700
+ * harmonization cost and the register choose among them; with
701
+ * `placement.octaveSearch` it is moved by octaves into a comfortable register,
702
+ * which leaves the key and the chords untouched. Both may be set, and the
703
+ * reported shift is their sum.
704
+ *
705
+ * The `seed` drives a deterministic tie-break only: it perturbs candidates by a
706
+ * magnitude far below any real cost difference (see `TIE_BREAK_JITTER`),
707
+ * so it can decide between chords or paths of otherwise-equal cost but never
708
+ * overrides melody fit or functional flow. For a well-determined melody the
709
+ * result is identical across seeds; the same seed always yields the same result.
710
+ *
711
+ * @param opts The melody and, optionally, the generation context, key, harmonic
712
+ * rhythm, reharmonization strength, placement search, meter, and seed. Only
713
+ * `melody` is required.
714
+ * @returns The chosen transpose, key, chord path, and per-note roles.
715
+ * @example
716
+ * ```ts
717
+ * import { harmonizeMelody } from '@libraz/libcantus';
718
+ * const result = harmonizeMelody({
719
+ * melody: [
720
+ * { pitch: 60, startBeat: 0, durationBeat: 1 },
721
+ * { pitch: 64, startBeat: 1, durationBeat: 1 },
722
+ * ],
723
+ * });
724
+ * result.chords; // one ChordSpan per chord change, on the harmonic-rhythm grid
725
+ * ```
726
+ * @category Reharmonization
727
+ */
728
+ declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
729
+
730
+ /**
731
+ * Reading a {@link CompositionPlan}'s harmony as a chord timeline.
732
+ *
733
+ * Kept apart from the plan types so the public reader can validate its plan
734
+ * without the types module importing the validator that imports it.
735
+ */
736
+
737
+ /**
738
+ * Read a plan's harmony as a chord timeline.
739
+ *
740
+ * The one way a generator or an evaluator reads chords out of a plan: each
741
+ * entry in `plan.harmony` is resolved against its key and placed at its own
742
+ * beat, so the timeline this returns always agrees with the plan it was built
743
+ * from.
744
+ *
745
+ * @param plan The plan to read harmony from.
746
+ * @returns A chord timeline spanning `plan.span`.
747
+ * @throws {InvalidInputError} If the plan is not a valid composition plan.
748
+ * @example
749
+ * ```ts
750
+ * import { planTimeline, resolveKey } from '@libraz/libcantus';
751
+ * const plan = {
752
+ * planVersion: 1, seed: 0, algorithmVersion: 1,
753
+ * keys: [resolveKey('C major')], meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
754
+ * span: { startBeat: 0, endBeat: 4, bars: 1 }, sections: [], phrases: [],
755
+ * harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }], motifs: [],
756
+ * rhythm: { onsetLevels: [1, 0, 0, 0, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
757
+ * };
758
+ * planTimeline(plan).at(0); // the I chord in C major
759
+ * ```
760
+ * @category Composition
761
+ */
762
+ declare function planTimeline(plan: CompositionPlan): ChordTimeline;
763
+
764
+ /**
765
+ * Boundary validation for {@link CompositionPlan}: a caller can hand this a
766
+ * value restored from JSON, a config file, or a plugin host, and every field
767
+ * is checked before a generator or evaluator reads it. A violation names the
768
+ * path to the offending field, so a malformed document is diagnosed at the
769
+ * field that is wrong rather than wherever the first bad read happens to land.
770
+ */
771
+
772
+ /**
773
+ * Reject a value that is not a {@link CompositionPlan}.
774
+ *
775
+ * A plan is the shape a caller's stored JSON, a config file, or a plugin host
776
+ * most plausibly hands back malformed: a missing field, a distribution that no
777
+ * longer sums to 1, an index a later edit left dangling, a numeral no reader
778
+ * can parse, a derivation that points at itself or at a later motif. Every
779
+ * field is checked before a generator or evaluator reads it, and a violation
780
+ * names the path to the field that is wrong.
781
+ *
782
+ * @param value The value to check.
783
+ * @param name What the value is, for the error message.
784
+ * @returns The same plan.
785
+ * @throws {InvalidInputError} If the value is not a valid composition plan.
786
+ * @example
787
+ * ```ts
788
+ * import { assertCompositionPlan } from '@libraz/libcantus';
789
+ * import { resolveKey } from '@libraz/libcantus';
790
+ * const plan = {
791
+ * planVersion: 1, seed: 0, algorithmVersion: 1,
792
+ * keys: [resolveKey('C major')],
793
+ * meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
794
+ * span: { startBeat: 0, endBeat: 4, bars: 1 },
795
+ * sections: [{ label: 'A', startBeat: 0, endBeat: 4 }],
796
+ * phrases: [],
797
+ * harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }],
798
+ * motifs: [],
799
+ * rhythm: { onsetLevels: [1, 0, 0, 0, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
800
+ * };
801
+ * assertCompositionPlan(plan); // the plan, unchanged
802
+ * ```
803
+ * @category Composition
804
+ */
805
+ declare function assertCompositionPlan(value: unknown, name?: string): CompositionPlan;
806
+
807
+ export { Articulation, BASS_LICKS, ChordLike, ChordSegment, ChordTimeline, CompositionPlan, DRUM_KIT, DRUM_PATTERNS, DrumHit, DrumStyle, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, GenerationContextInput, Genre, GridEvent, GrooveFeel, HarmonizeOptions, HarmonizeResult, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, MeterLike, NoteEvent, PercussionProfile, Section, StringedProfile, Vocabulary, assertCompositionPlan, classifyMelodyTones, harmonizeMelody, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, planTimeline, sustainsShift, sustainsStrokes };
808
+ export type { BassLick, ClassifiedMelodyTone, DrumPattern, DrumPatternOptions, DrumStroke, DrumVocabulary, FillArchetype, FillStroke, FillType, FillVelocity, ImitationAnswer, ImitationOptions, KickFigure, KickPattern, KickSlot, LickMaterial, LickNote, MelodyToneRole, PlaceLicksOptions };