@libraz/libcantus-wasm 0.0.0-stage → 1.4.1
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.
- package/LICENSE +201 -0
- package/NOTICE +63 -0
- package/README.md +75 -2
- package/dist/analyze/index.d.ts +341 -0
- package/dist/analyze/index.js +128 -0
- package/dist/backend.js +140 -0
- package/dist/cantus.js +2 -0
- package/dist/cantus.wasm +0 -0
- package/dist/chunk-6X5QS3NE.js +6941 -0
- package/dist/coerce-Cr9AZsTY.d.ts +1322 -0
- package/dist/core/index.d.ts +293 -0
- package/dist/core/index.js +224 -0
- package/dist/generate/index.d.ts +810 -0
- package/dist/generate/index.js +150 -0
- package/dist/index-C1dnzRkt.d.ts +2902 -0
- package/dist/index-C9MYbuKS.d.ts +804 -0
- package/dist/index-CBQLVwv_.d.ts +64 -0
- package/dist/index-COyI6W_w.d.ts +1363 -0
- package/dist/index-Cbs3SQe9.d.ts +665 -0
- package/dist/index-DInQqT8Q.d.ts +66 -0
- package/dist/index-wE8SecK5.d.ts +515 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +802 -0
- package/dist/masks-BDxvQO8b.d.ts +493 -0
- package/dist/model/index.d.ts +5964 -0
- package/dist/model/index.js +46 -0
- package/dist/positional-DLnfUgqG.d.ts +365 -0
- package/dist/profile-kmJqJ3aO.d.ts +1508 -0
- package/dist/theory/index.d.ts +990 -0
- package/dist/theory/index.js +288 -0
- package/dist/types-DPPzRpc3.d.ts +2599 -0
- package/package.json +93 -4
|
@@ -0,0 +1,810 @@
|
|
|
1
|
+
import { b as MeterLike } from '../index-wE8SecK5.js';
|
|
2
|
+
export { M as MeterChange, c as MeterMap, T as TimeSignature } from '../index-wE8SecK5.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-Cr9AZsTY.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-Cr9AZsTY.js';
|
|
7
|
+
import { h as ChordTimeline } from '../types-DPPzRpc3.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-DPPzRpc3.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-CBQLVwv_.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-C1dnzRkt.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-C1dnzRkt.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
|
+
/** Every melody tone role, in declaration order. */
|
|
623
|
+
declare const MELODY_TONE_ROLES: readonly ["structural", "passing", "neighbor", "appoggiatura", "suspension", "anticipation", "escape"];
|
|
624
|
+
/**
|
|
625
|
+
* What a melody note contributes to the harmony: either a structural tone the
|
|
626
|
+
* chord has to account for, or the ornament figure that explains it away.
|
|
627
|
+
*
|
|
628
|
+
* @category Reharmonization
|
|
629
|
+
*/
|
|
630
|
+
type MelodyToneRole = (typeof MELODY_TONE_ROLES)[number];
|
|
631
|
+
/**
|
|
632
|
+
* One melody note's classification: its index in the classified melody, the
|
|
633
|
+
* figure it forms, and whether that figure makes it ornamental.
|
|
634
|
+
*
|
|
635
|
+
* @category Reharmonization
|
|
636
|
+
*/
|
|
637
|
+
type ClassifiedMelodyTone = {
|
|
638
|
+
noteIndex: number;
|
|
639
|
+
role: MelodyToneRole;
|
|
640
|
+
/** True for every role but `'structural'`. */
|
|
641
|
+
ornamental: boolean;
|
|
642
|
+
};
|
|
643
|
+
/**
|
|
644
|
+
* Classify a melody's ornaments from the melody and the metre alone.
|
|
645
|
+
*
|
|
646
|
+
* This is deliberately chord-free: a harmonizer needs to know which notes the
|
|
647
|
+
* chords must explain *before* it can choose them, so nothing here may consult a
|
|
648
|
+
* harmony. What remains is the melodic and metric evidence — stepwise approach
|
|
649
|
+
* and departure, repeated pitches, leaps, and the relative metric weight and
|
|
650
|
+
* length of a note against its neighbours.
|
|
651
|
+
*
|
|
652
|
+
* The figures are recognized in the order suspension, passing, neighbor,
|
|
653
|
+
* anticipation, appoggiatura, escape. A note is judged ornamental only when it
|
|
654
|
+
* is metrically and rhythmically subordinate to the neighbours that frame it
|
|
655
|
+
* (or, for the accented figures, when it leans on a stronger beat than its
|
|
656
|
+
* approach and gives way to a resolution). A note without an adjacent
|
|
657
|
+
* predecessor and successor has no figure to belong to and stays structural, so
|
|
658
|
+
* the first and last notes of a phrase are always structural.
|
|
659
|
+
*
|
|
660
|
+
* The notes are read in onset order, ties by pitch, whatever order they are
|
|
661
|
+
* listed in. A note of zero length sounds nothing: it is structural and is no
|
|
662
|
+
* other note's neighbour.
|
|
663
|
+
*
|
|
664
|
+
* @param melody The melody, in any order.
|
|
665
|
+
* @param ts Time signature used to weight metric accents.
|
|
666
|
+
* @returns One classification per input note, in input order.
|
|
667
|
+
* @example
|
|
668
|
+
* ```ts
|
|
669
|
+
* import { classifyMelodyTones } from '@libraz/libcantus';
|
|
670
|
+
* const melody = [60, 62, 64, 60].map((pitch, i) => ({
|
|
671
|
+
* pitch,
|
|
672
|
+
* startBeat: i,
|
|
673
|
+
* durationBeat: 1,
|
|
674
|
+
* }));
|
|
675
|
+
* classifyMelodyTones(melody, { numerator: 4, denominator: 4 })[1];
|
|
676
|
+
* // { noteIndex: 1, role: 'passing', ornamental: true }
|
|
677
|
+
* ```
|
|
678
|
+
* @category Reharmonization
|
|
679
|
+
*/
|
|
680
|
+
declare function classifyMelodyTones(melody: readonly NoteEvent[], ts: MeterLike): ClassifiedMelodyTone[];
|
|
681
|
+
|
|
682
|
+
/**
|
|
683
|
+
* Harmonize a melody with a min-cost chord progression.
|
|
684
|
+
*
|
|
685
|
+
* The melody's ornaments are classified first, from the melody and the metre
|
|
686
|
+
* alone (see {@link classifyMelodyTones}); the chords then have to explain the
|
|
687
|
+
* structural tones only, so a passing tone no longer buys itself a chord. The
|
|
688
|
+
* melody is segmented by `harmonicRhythm`; each segment is scored against the
|
|
689
|
+
* candidate chords the harmonic dial opens — the key's own triads, then the
|
|
690
|
+
* secondary dominants, then the parallel mode's chords, one at a time as
|
|
691
|
+
* `ctx.complexity.harmonic` rises from 0 to 1 — by the fit of those structural
|
|
692
|
+
* tones, and a Viterbi search picks the lowest-cost path using a
|
|
693
|
+
* functional-flow transition cost and a cadence bonus at the end of the melody
|
|
694
|
+
* it is given — one cadence, at the close, unless `phraseEnds` names the closes
|
|
695
|
+
* inside a longer line, and then one at each of them as well. Runs of the same
|
|
696
|
+
* chord are reported once, so the chord count follows the harmony rather than
|
|
697
|
+
* the grid.
|
|
698
|
+
*
|
|
699
|
+
* With `placement.transposeSearch` the melody is moved into the key it is
|
|
700
|
+
* harmonized in, and `transposeSemitones` reports how far: the shifts that
|
|
701
|
+
* leave the fewest beats of the melody outside the key are kept, and the
|
|
702
|
+
* harmonization cost and the register choose among them; with
|
|
703
|
+
* `placement.octaveSearch` it is moved by octaves into a comfortable register,
|
|
704
|
+
* which leaves the key and the chords untouched. Both may be set, and the
|
|
705
|
+
* reported shift is their sum.
|
|
706
|
+
*
|
|
707
|
+
* The `seed` drives a deterministic tie-break only: it perturbs candidates by a
|
|
708
|
+
* magnitude far below any real cost difference (see `TIE_BREAK_JITTER`),
|
|
709
|
+
* so it can decide between chords or paths of otherwise-equal cost but never
|
|
710
|
+
* overrides melody fit or functional flow. For a well-determined melody the
|
|
711
|
+
* result is identical across seeds; the same seed always yields the same result.
|
|
712
|
+
*
|
|
713
|
+
* @param opts The melody and, optionally, the generation context, key, harmonic
|
|
714
|
+
* rhythm, reharmonization strength, placement search, meter, and seed. Only
|
|
715
|
+
* `melody` is required.
|
|
716
|
+
* @returns The chosen transpose, key, chord path, and per-note roles.
|
|
717
|
+
* @example
|
|
718
|
+
* ```ts
|
|
719
|
+
* import { harmonizeMelody } from '@libraz/libcantus';
|
|
720
|
+
* const result = harmonizeMelody({
|
|
721
|
+
* melody: [
|
|
722
|
+
* { pitch: 60, startBeat: 0, durationBeat: 1 },
|
|
723
|
+
* { pitch: 64, startBeat: 1, durationBeat: 1 },
|
|
724
|
+
* ],
|
|
725
|
+
* });
|
|
726
|
+
* result.chords; // one ChordSpan per chord change, on the harmonic-rhythm grid
|
|
727
|
+
* ```
|
|
728
|
+
* @category Reharmonization
|
|
729
|
+
*/
|
|
730
|
+
declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
|
|
731
|
+
|
|
732
|
+
/**
|
|
733
|
+
* Reading a {@link CompositionPlan}'s harmony as a chord timeline.
|
|
734
|
+
*
|
|
735
|
+
* Kept apart from the plan types so the public reader can validate its plan
|
|
736
|
+
* without the types module importing the validator that imports it.
|
|
737
|
+
*/
|
|
738
|
+
|
|
739
|
+
/**
|
|
740
|
+
* Read a plan's harmony as a chord timeline.
|
|
741
|
+
*
|
|
742
|
+
* The one way a generator or an evaluator reads chords out of a plan: each
|
|
743
|
+
* entry in `plan.harmony` is resolved against its key and placed at its own
|
|
744
|
+
* beat, so the timeline this returns always agrees with the plan it was built
|
|
745
|
+
* from.
|
|
746
|
+
*
|
|
747
|
+
* @param plan The plan to read harmony from.
|
|
748
|
+
* @returns A chord timeline spanning `plan.span`.
|
|
749
|
+
* @throws {InvalidInputError} If the plan is not a valid composition plan.
|
|
750
|
+
* @example
|
|
751
|
+
* ```ts
|
|
752
|
+
* import { planTimeline, resolveKey } from '@libraz/libcantus';
|
|
753
|
+
* const plan = {
|
|
754
|
+
* planVersion: 1, seed: 0, algorithmVersion: 1,
|
|
755
|
+
* keys: [resolveKey('C major')], meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
|
|
756
|
+
* span: { startBeat: 0, endBeat: 4, bars: 1 }, sections: [], phrases: [],
|
|
757
|
+
* harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }], motifs: [],
|
|
758
|
+
* rhythm: { onsetLevels: [1, 0, 0, 0, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
|
|
759
|
+
* };
|
|
760
|
+
* planTimeline(plan).at(0); // the I chord in C major
|
|
761
|
+
* ```
|
|
762
|
+
* @category Composition
|
|
763
|
+
*/
|
|
764
|
+
declare function planTimeline(plan: CompositionPlan): ChordTimeline;
|
|
765
|
+
|
|
766
|
+
/**
|
|
767
|
+
* Boundary validation for {@link CompositionPlan}: a caller can hand this a
|
|
768
|
+
* value restored from JSON, a config file, or a plugin host, and every field
|
|
769
|
+
* is checked before a generator or evaluator reads it. A violation names the
|
|
770
|
+
* path to the offending field, so a malformed document is diagnosed at the
|
|
771
|
+
* field that is wrong rather than wherever the first bad read happens to land.
|
|
772
|
+
*/
|
|
773
|
+
|
|
774
|
+
/**
|
|
775
|
+
* Reject a value that is not a {@link CompositionPlan}.
|
|
776
|
+
*
|
|
777
|
+
* A plan is the shape a caller's stored JSON, a config file, or a plugin host
|
|
778
|
+
* most plausibly hands back malformed: a missing field, a distribution that no
|
|
779
|
+
* longer sums to 1, an index a later edit left dangling, a numeral no reader
|
|
780
|
+
* can parse, a derivation that points at itself or at a later motif. Every
|
|
781
|
+
* field is checked before a generator or evaluator reads it, and a violation
|
|
782
|
+
* names the path to the field that is wrong.
|
|
783
|
+
*
|
|
784
|
+
* @param value The value to check.
|
|
785
|
+
* @param name What the value is, for the error message.
|
|
786
|
+
* @returns The same plan.
|
|
787
|
+
* @throws {InvalidInputError} If the value is not a valid composition plan.
|
|
788
|
+
* @example
|
|
789
|
+
* ```ts
|
|
790
|
+
* import { assertCompositionPlan } from '@libraz/libcantus';
|
|
791
|
+
* import { resolveKey } from '@libraz/libcantus';
|
|
792
|
+
* const plan = {
|
|
793
|
+
* planVersion: 1, seed: 0, algorithmVersion: 1,
|
|
794
|
+
* keys: [resolveKey('C major')],
|
|
795
|
+
* meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
|
|
796
|
+
* span: { startBeat: 0, endBeat: 4, bars: 1 },
|
|
797
|
+
* sections: [{ label: 'A', startBeat: 0, endBeat: 4 }],
|
|
798
|
+
* phrases: [],
|
|
799
|
+
* harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }],
|
|
800
|
+
* motifs: [],
|
|
801
|
+
* rhythm: { onsetLevels: [1, 0, 0, 0, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
|
|
802
|
+
* };
|
|
803
|
+
* assertCompositionPlan(plan); // the plan, unchanged
|
|
804
|
+
* ```
|
|
805
|
+
* @category Composition
|
|
806
|
+
*/
|
|
807
|
+
declare function assertCompositionPlan(value: unknown, name?: string): CompositionPlan;
|
|
808
|
+
|
|
809
|
+
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 };
|
|
810
|
+
export type { BassLick, ClassifiedMelodyTone, DrumPattern, DrumPatternOptions, DrumStroke, DrumVocabulary, FillArchetype, FillStroke, FillType, FillVelocity, ImitationAnswer, ImitationOptions, KickFigure, KickPattern, KickSlot, LickMaterial, LickNote, MelodyToneRole, PlaceLicksOptions };
|