@libraz/libcantus 1.0.1 → 1.1.0

package/dist/generate/index.cjs

@@ -66,13 +66,13 @@
 
 
 
-var _chunkAFM2ULJHcjs = require('../chunk-AFM2ULJH.cjs');
-require('../chunk-OE6WK2Y2.cjs');
-require('../chunk-E3F4AHAH.cjs');
-require('../chunk-K4ZJUGF4.cjs');
-require('../chunk-6XPTBE7Y.cjs');
-require('../chunk-UADYAYAT.cjs');
-require('../chunk-Q2WGKJNN.cjs');
+var _chunk5KW7DNCJcjs = require('../chunk-5KW7DNCJ.cjs');
+require('../chunk-Q6R3QAZD.cjs');
+require('../chunk-J772DL3B.cjs');
+require('../chunk-TT6PKMPR.cjs');
+require('../chunk-R7B5N2JK.cjs');
+require('../chunk-YPB3A3EY.cjs');
+require('../chunk-XKSO2V5I.cjs');
 
 
 
@@ -141,5 +141,5 @@ require('../chunk-Q2WGKJNN.cjs');
 
 
 
-exports.BAR_STEPS = _chunkAFM2ULJHcjs.BAR_STEPS; exports.BASS_LICKS = _chunkAFM2ULJHcjs.BASS_LICKS; exports.BASS_STYLES = _chunkAFM2ULJHcjs.BASS_STYLES; exports.BEAT_STEPS = _chunkAFM2ULJHcjs.BEAT_STEPS; exports.BORROWED_DEGREES = _chunkAFM2ULJHcjs.BORROWED_DEGREES; exports.DRUM_KIT = _chunkAFM2ULJHcjs.DRUM_KIT; exports.DRUM_NOTES = _chunkAFM2ULJHcjs.DRUM_NOTES; exports.DRUM_PATTERNS = _chunkAFM2ULJHcjs.DRUM_PATTERNS; exports.FILL_ARCHETYPES = _chunkAFM2ULJHcjs.FILL_ARCHETYPES; exports.FILL_TYPES = _chunkAFM2ULJHcjs.FILL_TYPES; exports.GENRES = _chunkAFM2ULJHcjs.GENRES; exports.KICK_FIGURES = _chunkAFM2ULJHcjs.KICK_FIGURES; exports.KICK_STEPS = _chunkAFM2ULJHcjs.KICK_STEPS; exports.MAX_DIFFICULTY = _chunkAFM2ULJHcjs.MAX_DIFFICULTY; exports.MIN_DIFFICULTY = _chunkAFM2ULJHcjs.MIN_DIFFICULTY; exports.ORNAMENT_STYLES = _chunkAFM2ULJHcjs.ORNAMENT_STYLES; exports.PROVENANCE_BASES = _chunkAFM2ULJHcjs.PROVENANCE_BASES; exports.STEP_BEATS = _chunkAFM2ULJHcjs.STEP_BEATS; exports.applyGrooveTemplate = _chunkAFM2ULJHcjs.applyGrooveTemplate; exports.assertVocabulary = _chunkAFM2ULJHcjs.assertVocabulary; exports.classifyMelodyTones = _chunkAFM2ULJHcjs.classifyMelodyTones; exports.deform = _chunkAFM2ULJHcjs.deform; exports.developMotif = _chunkAFM2ULJHcjs.developMotif; exports.double = _chunkAFM2ULJHcjs.double; exports.doubleTime = _chunkAFM2ULJHcjs.doubleTime; exports.drumVoiceOf = _chunkAFM2ULJHcjs.drumVoiceOf; exports.extractGrooveTemplate = _chunkAFM2ULJHcjs.extractGrooveTemplate; exports.fitsQuery = _chunkAFM2ULJHcjs.fitsQuery; exports.generateBassLine = _chunkAFM2ULJHcjs.generateBassLine; exports.generateCounterMelody = _chunkAFM2ULJHcjs.generateCounterMelody; exports.generateDrums = _chunkAFM2ULJHcjs.generateDrums; exports.generateMotif = _chunkAFM2ULJHcjs.generateMotif; exports.generateProgression = _chunkAFM2ULJHcjs.generateProgression; exports.generateRhythm = _chunkAFM2ULJHcjs.generateRhythm; exports.gridMetricWeight = _chunkAFM2ULJHcjs.gridMetricWeight; exports.halfTime = _chunkAFM2ULJHcjs.halfTime; exports.harmonizeMelody = _chunkAFM2ULJHcjs.harmonizeMelody; exports.humanize = _chunkAFM2ULJHcjs.humanize; exports.imitate = _chunkAFM2ULJHcjs.imitate; exports.isDrumPattern = _chunkAFM2ULJHcjs.isDrumPattern; exports.isFillArchetype = _chunkAFM2ULJHcjs.isFillArchetype; exports.isLickMaterial = _chunkAFM2ULJHcjs.isLickMaterial; exports.mergeVocabulary = _chunkAFM2ULJHcjs.mergeVocabulary; exports.modalInterchangePalette = _chunkAFM2ULJHcjs.modalInterchangePalette; exports.motifToNoteEvents = _chunkAFM2ULJHcjs.motifToNoteEvents; exports.negativeHarmonyMirror = _chunkAFM2ULJHcjs.negativeHarmonyMirror; exports.onsetWeightCurve = _chunkAFM2ULJHcjs.onsetWeightCurve; exports.ornament = _chunkAFM2ULJHcjs.ornament; exports.ornamentBy = _chunkAFM2ULJHcjs.ornamentBy; exports.pickProgressionPreset = _chunkAFM2ULJHcjs.pickProgressionPreset; exports.pickVocabulary = _chunkAFM2ULJHcjs.pickVocabulary; exports.placeDrumPattern = _chunkAFM2ULJHcjs.placeDrumPattern; exports.placeLicks = _chunkAFM2ULJHcjs.placeLicks; exports.progressions = _chunkAFM2ULJHcjs.progressions; exports.progressionsByStyle = _chunkAFM2ULJHcjs.progressionsByStyle; exports.resolveContext = _chunkAFM2ULJHcjs.resolveContext; exports.rhythmDensity = _chunkAFM2ULJHcjs.rhythmDensity; exports.rhythmToNoteEvents = _chunkAFM2ULJHcjs.rhythmToNoteEvents; exports.selectVocabulary = _chunkAFM2ULJHcjs.selectVocabulary; exports.substituteChord = _chunkAFM2ULJHcjs.substituteChord; exports.sustainsShift = _chunkAFM2ULJHcjs.sustainsShift; exports.sustainsStrokes = _chunkAFM2ULJHcjs.sustainsStrokes; exports.syncopate = _chunkAFM2ULJHcjs.syncopate; exports.thin = _chunkAFM2ULJHcjs.thin; exports.transformMotif = _chunkAFM2ULJHcjs.transformMotif; exports.vocabularyOfKind = _chunkAFM2ULJHcjs.vocabularyOfKind; exports.withinCeiling = _chunkAFM2ULJHcjs.withinCeiling;
+exports.BAR_STEPS = _chunk5KW7DNCJcjs.BAR_STEPS; exports.BASS_LICKS = _chunk5KW7DNCJcjs.BASS_LICKS; exports.BASS_STYLES = _chunk5KW7DNCJcjs.BASS_STYLES; exports.BEAT_STEPS = _chunk5KW7DNCJcjs.BEAT_STEPS; exports.BORROWED_DEGREES = _chunk5KW7DNCJcjs.BORROWED_DEGREES; exports.DRUM_KIT = _chunk5KW7DNCJcjs.DRUM_KIT; exports.DRUM_NOTES = _chunk5KW7DNCJcjs.DRUM_NOTES; exports.DRUM_PATTERNS = _chunk5KW7DNCJcjs.DRUM_PATTERNS; exports.FILL_ARCHETYPES = _chunk5KW7DNCJcjs.FILL_ARCHETYPES; exports.FILL_TYPES = _chunk5KW7DNCJcjs.FILL_TYPES; exports.GENRES = _chunk5KW7DNCJcjs.GENRES; exports.KICK_FIGURES = _chunk5KW7DNCJcjs.KICK_FIGURES; exports.KICK_STEPS = _chunk5KW7DNCJcjs.KICK_STEPS; exports.MAX_DIFFICULTY = _chunk5KW7DNCJcjs.MAX_DIFFICULTY; exports.MIN_DIFFICULTY = _chunk5KW7DNCJcjs.MIN_DIFFICULTY; exports.ORNAMENT_STYLES = _chunk5KW7DNCJcjs.ORNAMENT_STYLES; exports.PROVENANCE_BASES = _chunk5KW7DNCJcjs.PROVENANCE_BASES; exports.STEP_BEATS = _chunk5KW7DNCJcjs.STEP_BEATS; exports.applyGrooveTemplate = _chunk5KW7DNCJcjs.applyGrooveTemplate; exports.assertVocabulary = _chunk5KW7DNCJcjs.assertVocabulary; exports.classifyMelodyTones = _chunk5KW7DNCJcjs.classifyMelodyTones; exports.deform = _chunk5KW7DNCJcjs.deform; exports.developMotif = _chunk5KW7DNCJcjs.developMotif; exports.double = _chunk5KW7DNCJcjs.double; exports.doubleTime = _chunk5KW7DNCJcjs.doubleTime; exports.drumVoiceOf = _chunk5KW7DNCJcjs.drumVoiceOf; exports.extractGrooveTemplate = _chunk5KW7DNCJcjs.extractGrooveTemplate; exports.fitsQuery = _chunk5KW7DNCJcjs.fitsQuery; exports.generateBassLine = _chunk5KW7DNCJcjs.generateBassLine; exports.generateCounterMelody = _chunk5KW7DNCJcjs.generateCounterMelody; exports.generateDrums = _chunk5KW7DNCJcjs.generateDrums; exports.generateMotif = _chunk5KW7DNCJcjs.generateMotif; exports.generateProgression = _chunk5KW7DNCJcjs.generateProgression; exports.generateRhythm = _chunk5KW7DNCJcjs.generateRhythm; exports.gridMetricWeight = _chunk5KW7DNCJcjs.gridMetricWeight; exports.halfTime = _chunk5KW7DNCJcjs.halfTime; exports.harmonizeMelody = _chunk5KW7DNCJcjs.harmonizeMelody; exports.humanize = _chunk5KW7DNCJcjs.humanize; exports.imitate = _chunk5KW7DNCJcjs.imitate; exports.isDrumPattern = _chunk5KW7DNCJcjs.isDrumPattern; exports.isFillArchetype = _chunk5KW7DNCJcjs.isFillArchetype; exports.isLickMaterial = _chunk5KW7DNCJcjs.isLickMaterial; exports.mergeVocabulary = _chunk5KW7DNCJcjs.mergeVocabulary; exports.modalInterchangePalette = _chunk5KW7DNCJcjs.modalInterchangePalette; exports.motifToNoteEvents = _chunk5KW7DNCJcjs.motifToNoteEvents; exports.negativeHarmonyMirror = _chunk5KW7DNCJcjs.negativeHarmonyMirror; exports.onsetWeightCurve = _chunk5KW7DNCJcjs.onsetWeightCurve; exports.ornament = _chunk5KW7DNCJcjs.ornament; exports.ornamentBy = _chunk5KW7DNCJcjs.ornamentBy; exports.pickProgressionPreset = _chunk5KW7DNCJcjs.pickProgressionPreset; exports.pickVocabulary = _chunk5KW7DNCJcjs.pickVocabulary; exports.placeDrumPattern = _chunk5KW7DNCJcjs.placeDrumPattern; exports.placeLicks = _chunk5KW7DNCJcjs.placeLicks; exports.progressions = _chunk5KW7DNCJcjs.progressions; exports.progressionsByStyle = _chunk5KW7DNCJcjs.progressionsByStyle; exports.resolveContext = _chunk5KW7DNCJcjs.resolveContext; exports.rhythmDensity = _chunk5KW7DNCJcjs.rhythmDensity; exports.rhythmToNoteEvents = _chunk5KW7DNCJcjs.rhythmToNoteEvents; exports.selectVocabulary = _chunk5KW7DNCJcjs.selectVocabulary; exports.substituteChord = _chunk5KW7DNCJcjs.substituteChord; exports.sustainsShift = _chunk5KW7DNCJcjs.sustainsShift; exports.sustainsStrokes = _chunk5KW7DNCJcjs.sustainsStrokes; exports.syncopate = _chunk5KW7DNCJcjs.syncopate; exports.thin = _chunk5KW7DNCJcjs.thin; exports.transformMotif = _chunk5KW7DNCJcjs.transformMotif; exports.vocabularyOfKind = _chunk5KW7DNCJcjs.vocabularyOfKind; exports.withinCeiling = _chunk5KW7DNCJcjs.withinCeiling;
 //# sourceMappingURL=index.cjs.map

package/dist/generate/index.d.cts

@@ -1,14 +1,15 @@
-import { a as Articulation, g as NoteEvent, I as IntervalLike } from '../index-B9MNZboQ.cjs';
-export { b as IntervalQualityLabel, d as KeyScale, S as SpelledInterval } from '../index-B9MNZboQ.cjs';
-import { e as ChordSegment, c as ChordLike, K as KeyLike } from '../index-C_8o--VE.cjs';
-export { b as ChordData, d as ChordQuality, g as ChordSpan, j as ChordToneRole, l as PitchSpelling, m as ProfileWeights } from '../index-C_8o--VE.cjs';
-export { B as BorrowedSource, e as ChordTimeline, H as HarmonicFunction } from '../index-Dzr13q3d.cjs';
-import { f as StringedProfile, P as PercussionProfile, c as Limb } from '../positional-DvH_sd8u.cjs';
-export { I as InstrumentProfile, a as InstrumentProfileCommon, d as PositionalRng, S as SeedPath } from '../positional-DvH_sd8u.cjs';
-import { T as TimeSignature } from '../index-BkGmlyI3.cjs';
-export { H as HarmonyRole } from '../index-B4o55NDr.cjs';
-import { a3 as Vocabulary, s as GridEvent, r as Genre, q as GenerationContextInput, m as DrumStyle, $ as Section, n as DrumVoice, t as GrooveFeel, k as DrumHit } from '../index-BGFW-8P2.cjs';
-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 Complexity, h as CounterMelodyOptions, D as DRUM_NOTES, i as DeformOptions, j as Draw, l as DrumRole, o as DrumsOptions, E as EuclideanKick, G as GENRES, p as GenerationContext, u as GrooveSlot, v as GrooveStyle, w as GrooveTemplate, H as HarmonizeOptions, x as HarmonizePlacement, y as HarmonizeResult, z as HumanizeOptions, M as MelodyNote, A as MotifCell, F as MotifContour, I as MotifNote, J as MotifOptions, K as MotifTransform, O as ORNAMENT_STYLES, L as OrnamentOptions, N as OrnamentStyle, P as PROVENANCE_BASES, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, T as ProgressionOptions, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, X as ResolvedContext, Y as RhythmEvent, Z as RhythmOptions, _ as STEP_BEATS, a0 as SubstituteOptions, a1 as Substitution, a2 as SubstitutionType, a4 as VocabularyQuery, a5 as applyGrooveTemplate, a6 as assertVocabulary, a7 as deform, a8 as developMotif, a9 as double, aa as doubleTime, ab as drumVoiceOf, ac as extractGrooveTemplate, ad as fitsQuery, ae as generateBassLine, af as generateCounterMelody, ag as generateDrums, ah as generateMotif, ai as generateProgression, aj as generateRhythm, ak as gridMetricWeight, al as halfTime, am as harmonizeMelody, an as humanize, ao as mergeVocabulary, ap as modalInterchangePalette, aq as motifToNoteEvents, ar as negativeHarmonyMirror, as as onsetWeightCurve, at as ornament, au as ornamentBy, av as pickProgressionPreset, aw as pickVocabulary, ax as progressions, ay as progressionsByStyle, az as resolveContext, aA as rhythmDensity, aB as rhythmToNoteEvents, aC as selectVocabulary, aD as substituteChord, aE as syncopate, aF as thin, aG as transformMotif, aH as vocabularyOfKind, aI as withinCeiling } from '../index-BGFW-8P2.cjs';
+import { h as NoteEvent, a as Articulation, b as IntervalLike } from '../index-Cy15oTvh.cjs';
+export { I as IntervalData, c as IntervalQualityLabel, e as KeyScale, g as NoteData, S as SpelledInterval } from '../index-Cy15oTvh.cjs';
+import { e as ChordSegment, c as ChordLike, K as KeyLike } from '../coerce-CJlgULrQ.cjs';
+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, q as SpelledKeyLike, r as SpelledKeyScale } from '../coerce-CJlgULrQ.cjs';
+export { B as BorrowedSource, e as ChordTimeline, H as HarmonicFunction } from '../index-B3WCj_Hm.cjs';
+import { f as StringedProfile, P as PercussionProfile, c as Limb } from '../positional-DMZer-FM.cjs';
+export { I as InstrumentProfile, a as InstrumentProfileCommon, d as PositionalRng, S as SeedPath } from '../positional-DMZer-FM.cjs';
+import { b as MeterLike } from '../index-D_hzxD8w.cjs';
+export { M as MeterChange, c as MeterMap, T as TimeSignature } from '../index-D_hzxD8w.cjs';
+export { H as HarmonyRole } from '../index-CBCP84rv.cjs';
+import { r as Genre, q as GenerationContextInput, a4 as Vocabulary, s as GridEvent, m as DrumStyle, $ as Section, n as DrumVoice, t as GrooveFeel, k as DrumHit, H as HarmonizeOptions, y as HarmonizeResult } from '../index-BzLNkmA7.cjs';
+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 Complexity, h as CounterMelodyOptions, D as DRUM_NOTES, i as DeformOptions, j as Draw, l as DrumRole, o as DrumsOptions, E as EuclideanKick, G as GENRES, p as GenerationContext, u as GrooveSlot, v as GrooveStyle, w as GrooveTemplate, x as HarmonizePlacement, z as HumanizeOptions, M as MelodyNote, A as MotifCell, F as MotifContour, I as MotifNote, J as MotifOptions, K as MotifTransform, O as ORNAMENT_STYLES, L as OrnamentOptions, N as OrnamentStyle, P as PROVENANCE_BASES, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, T as ProgressionOptions, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, X as ResolvedContext, Y as RhythmEvent, Z as RhythmOptions, _ as STEP_BEATS, a0 as SubstituteOptions, a1 as Substitution, a2 as SubstitutionType, a3 as SyncopateOptions, a5 as VocabularyQuery, a6 as applyGrooveTemplate, a7 as assertVocabulary, a8 as deform, a9 as developMotif, aa as double, ab as doubleTime, ac as drumVoiceOf, ad as extractGrooveTemplate, ae as fitsQuery, af as generateBassLine, ag as generateCounterMelody, ah as generateDrums, ai as generateMotif, aj as generateProgression, ak as generateRhythm, al as gridMetricWeight, am as halfTime, an as humanize, ao as mergeVocabulary, ap as modalInterchangePalette, aq as motifToNoteEvents, ar as negativeHarmonyMirror, as as onsetWeightCurve, at as ornament, au as ornamentBy, av as pickProgressionPreset, aw as pickVocabulary, ax as progressions, ay as progressionsByStyle, az as resolveContext, aA as rhythmDensity, aB as rhythmToNoteEvents, aC as selectVocabulary, aD as substituteChord, aE as syncopate, aF as thin, aG as transformMotif, aH as vocabularyOfKind, aI as withinCeiling } from '../index-BzLNkmA7.cjs';
 
 /**
  * The playing-difficulty ceiling, as the generators apply it.
@@ -47,65 +48,15 @@ declare function sustainsStrokes(stepBeats: number, bpm: number | undefined, dif
 declare function sustainsShift(semitones: number, stepBeats: number, bpm: number | undefined, difficulty: number | undefined): boolean;
 
 /**
- * The bass lick dictionary: the figures a bass player reaches for, held as
- * chord-relative degrees and beat positions and deformed to fit the progression
- * actually in front of them.
+ * Lay the figures of the dictionary over a chord progression.
  *
- * Provenance: no entry reproduces a bass line from a particular song. Each is a
- * figure that belongs to nobody — the descending soul walk-down, the octave
- * slap, the boogie shuffle — of the kind every player of that music already
- * plays, and each records the ground it qualifies under.
+ * A segment takes a figure its genre plays, chosen by a draw addressed to that
+ * segment, and the figure's degrees are read against the chord sounding under
+ * it. What the figures are is `licks-data.ts`; which pitch a degree asks for is
+ * `degrees.ts`. This module is what places them: which segment takes one, how
+ * it is fitted to the span, and how one figure leads into the next.
  */
 
-/**
- * One note of a lick, relative to the chord it is played over.
- *
- * A degree is 1-based and counts up from the chord's root: 1 is the root, 3 the
- * third, 8 the octave. Degrees the chord itself names — the third, fifth and
- * seventh — are taken from the chord, so the same figure comes out major over a
- * major chord and minor over a minor one; the rest are taken from the key. That
- * is what lets a figure be written once and fit a whole progression.
- *
- * @category Composition
- */
-type LickNote = GridEvent & {
-    /** Chord degree, 1-based; 8 is the octave above the root. */
-    degree: number;
-    /** Chromatic alteration in semitones, for a flattened or raised degree. */
-    alter?: number;
-    /** Sounding length in sixteenths; one step when absent. */
-    lengthSteps?: number;
-    /** How the note is played, when it is more than a plain note. */
-    articulation?: Articulation;
-};
-/**
- * A lick: its notes and how long the whole figure lasts.
- *
- * @category Composition
- */
-type LickMaterial = {
-    /** Length of the figure in sixteenths. */
-    lengthSteps: number;
-    notes: LickNote[];
-};
-/**
- * A lick with the conditions it fits.
- *
- * @category Composition
- */
-type BassLick = Vocabulary<LickMaterial>;
-/**
- * Whether a caller's material is a bass lick.
- *
- * @category Composition
- */
-declare function isLickMaterial(material: unknown): material is LickMaterial;
-/**
- * The built-in bass licks, in declaration order.
- *
- * @category Composition
- */
-declare const BASS_LICKS: readonly BassLick[];
 /**
  * Options controlling {@link placeLicks}.
  *
@@ -122,8 +73,8 @@ type PlaceLicksOptions = {
      * `ctx: { complexity: { difficulty } }`; the context wins over both.
      */
     difficulty?: number;
-    /** Time signature; defaults to 4/4. */
-    ts?: TimeSignature;
+    /** Time signature, in any form that names one; defaults to 4/4. */
+    ts?: MeterLike;
     /**
      * Target register as a base MIDI octave; roots land around `octave*12+12`.
      *
@@ -147,9 +98,10 @@ type PlaceLicksOptions = {
      */
     ctx?: GenerationContextInput;
     /**
-     * Maximum number of segments {@link placeLicks} may lay figures over. One
-     * figure is placed per segment, so this is the guard against an unbounded
-     * caller rather than a limit on any search.
+     * Maximum number of segments {@link placeLicks} may lay figures over, and of
+     * bars those segments span. One figure is placed per bar of a segment, so
+     * both are counted: this is the guard against an unbounded caller — a segment
+     * running to a beat far past the music — rather than a limit on any search.
      *
      * @defaultValue 1000000
      */
@@ -171,8 +123,10 @@ type PlaceLicksOptions = {
  *   key name such as `'C major'` is read as that key.
  * @param opts Genre, density, ceiling and seed.
  * @returns Bass notes sorted by onset, non-overlapping.
- * @throws If a segment has a non-positive duration, or the genre is not one
- *   this library names.
+ * @throws If a segment has a non-positive duration, two segments overlap, or
+ *   the genre is not one this library names. A bass part is monophonic, so
+ *   overlapping segments are refused here exactly as {@link generateBassLine}
+ *   refuses them rather than being laid over each other.
  *
  * @example
  * ```ts
@@ -190,6 +144,74 @@ declare function placeLicks(timeline: readonly (Omit<ChordSegment, 'chord'> & {
     chord: ChordLike;
 })[], key: KeyLike, opts: PlaceLicksOptions): NoteEvent[];
 
+/**
+ * The bass lick dictionary: the figures a bass player reaches for, held as
+ * chord-relative degrees and beat positions and deformed to fit the progression
+ * actually in front of them.
+ *
+ * Provenance: no entry reproduces a bass line from a particular song. Each is a
+ * figure that belongs to nobody — the descending soul walk-down, the octave
+ * slap, the boogie shuffle — of the kind every player of that music already
+ * plays, and each records the ground it qualifies under.
+ */
+
+/**
+ * One note of a lick, relative to the chord it is played over.
+ *
+ * A degree is 1-based and counts up from the chord's root: 1 is the root, 3 the
+ * third, 8 the octave. Degrees the chord itself names — the third, fifth and
+ * seventh — are taken from the chord, so the same figure comes out major over a
+ * major chord and minor over a minor one. A degree the chord's quality settles
+ * without stating it follows the quality: the third of a suspended chord is the
+ * tone the suspension put there, and a seventh chord's remaining degrees are
+ * its own chord scale's. Only what the harmony leaves open is taken from the
+ * key. That is what lets a figure be written once and fit a whole progression.
+ *
+ * @category Composition
+ */
+type LickNote = GridEvent & {
+    /** Chord degree, 1-based; 8 is the octave above the root. */
+    degree: number;
+    /** Chromatic alteration in semitones, for a flattened or raised degree. */
+    alter?: number;
+    /**
+     * Sounding length in sixteenths. Absent, the note sounds to the next onset,
+     * as a line written by {@link generateBassLine} does: the built-in figures
+     * name no length, so a figure is legato unless it says otherwise.
+     */
+    lengthSteps?: number;
+    /** How the note is played, when it is more than a plain note. */
+    articulation?: Articulation;
+};
+/**
+ * A lick: its notes and how long the whole figure lasts.
+ *
+ * @category Composition
+ */
+type LickMaterial = {
+    /** Length of the figure in sixteenths. */
+    lengthSteps: number;
+    notes: LickNote[];
+};
+/**
+ * A lick with the conditions it fits.
+ *
+ * @category Composition
+ */
+type BassLick = Vocabulary<LickMaterial>;
+/**
+ * Whether a caller's material is a bass lick.
+ *
+ * @category Composition
+ */
+declare function isLickMaterial(material: unknown): material is LickMaterial;
+/**
+ * The built-in bass licks, in declaration order.
+ *
+ * @category Composition
+ */
+declare const BASS_LICKS: readonly BassLick[];
+
 /**
  * Imitative entries: a second voice restating what the first has just sung.
  *
@@ -207,8 +229,10 @@ declare const IMITATION_ANSWERS: readonly ["real", "tonal"];
  *
  * A `real` answer transposes literally, keeping every interval of the subject
  * and leaving the key where the interval puts it. A `tonal` answer counts scale
- * degrees instead, so the answer stays in the key and adjusts an interval or two
- * to do it — the fifth of a subject answered by a fourth.
+ * degrees instead, so the answer stays in the key: every interval keeps the
+ * number of degrees it spanned in the subject, and only its quality changes as
+ * the key's own pattern of steps and half steps asks — a major third answered by
+ * a minor one.
  *
  * @category Composition
  */
@@ -280,7 +304,9 @@ type ImitationOptions = {
  * @param opts Where the answer enters, at what interval, and in what key.
  * @returns The imitation as note events sorted by onset; `[]` when the chosen
  *   span holds no sounding notes. Notes with a zero or negative duration never
- *   sound and are not copied, so the answer can be shorter than the span.
+ *   sound and are not copied, so the answer can be shorter than the span. Every
+ *   other field of a copied note — its articulation, and its velocity through
+ *   `velocityScale` — comes across with it.
  * @throws If the span is reversed, the answer is not a known kind, or a
  *   transposed pitch leaves the MIDI range.
  * @example
@@ -344,9 +370,14 @@ type FillArchetype = {
     /** Strokes per beat of the bar, indexed 0..3. */
     atBeat: readonly (readonly FillStroke[])[];
     /**
-     * Whether a bar longer than four beats keeps playing the last beat's strokes.
-     * The archetypes are written against a four-beat bar; most read naturally when
-     * extended, but the half-time figure is a bar-long gesture and stops there.
+     * Whether the archetype stops where its own strokes stop, rather than holding
+     * its last beat over the beats of the bar it does not write.
+     *
+     * It answers for an archetype shorter than the bar it is placed in, so the
+     * built-in archetypes — written beat by beat against the four-beat bar
+     * {@link generateDrums} accepts — are unaffected by it; a caller's archetype
+     * that writes fewer beats is where it decides anything. Most figures read
+     * naturally when held, but a half-time gesture is bar-long and stops there.
      */
     boundToBar?: boolean;
 };
@@ -425,6 +456,11 @@ declare const KICK_FIGURES: Readonly<Record<DrumStyle, KickFigure>>;
  * hand at the same instant is what makes a pattern unplayable, and a voice no
  * limb reaches is not on the kit at all.
  *
+ * The auxiliary percussion — hand-claps, tambourine, shaker — is dubbed over
+ * the kit on a pass of its own, so it sounds through a backbeat whose snare and
+ * hi-hat already take both hands, and the four limbs stay the bound on the
+ * groove itself.
+ *
  * @example
  * ```ts
  * import { DRUM_KIT, generateDrums, playability } from '@libraz/libcantus';
@@ -511,8 +547,8 @@ type DrumPatternOptions = {
     genre: Genre;
     /** Section the pattern plays in, matched against each entry's own sections. */
     section?: Section;
-    /** Time signature; defaults to 4/4. */
-    ts?: TimeSignature;
+    /** Time signature, in any form that names one; defaults to 4/4. */
+    ts?: MeterLike;
     /**
      * The generation context. `bpm` is the tempo, `complexity.rhythmic` thins the
      * figure below its middle setting and syncopates it above,
@@ -631,6 +667,54 @@ type ClassifiedMelodyTone = {
  * ```
  * @category Reharmonization
  */
-declare function classifyMelodyTones(melody: readonly NoteEvent[], ts: TimeSignature): ClassifiedMelodyTone[];
+declare function classifyMelodyTones(melody: readonly NoteEvent[], ts: MeterLike): ClassifiedMelodyTone[];
+
+/**
+ * Harmonize a melody with a min-cost chord progression.
+ *
+ * The melody's ornaments are classified first, from the melody and the metre
+ * alone (see {@link classifyMelodyTones}); the chords then have to explain the
+ * structural tones only, so a passing tone no longer buys itself a chord. The
+ * melody is segmented by `harmonicRhythm`; each segment is scored against the
+ * candidate chords the harmonic dial opens — the key's own triads, then the
+ * secondary dominants, then the parallel mode's chords, one at a time as
+ * `ctx.complexity.harmonic` rises from 0 to 1 — by the fit of those structural
+ * tones, and a Viterbi search picks the lowest-cost path using a
+ * functional-flow transition cost and a cadence bonus at the end of the melody
+ * it is given — one cadence, at the close, unless `phraseEnds` names the closes
+ * inside a longer line, and then one at each of them as well. Runs of the same
+ * chord are reported once, so the chord count follows the harmony rather than
+ * the grid.
+ *
+ * With `placement.transposeSearch` the melody is moved into the key it is
+ * harmonized in, and `transposeSemitones` reports how far; with
+ * `placement.octaveSearch` it is moved by octaves into a comfortable register,
+ * which leaves the key and the chords untouched. Both may be set, and the
+ * reported shift is their sum.
+ *
+ * The `seed` drives a deterministic tie-break only: it perturbs candidates by a
+ * magnitude far below any real cost difference (see `TIE_BREAK_JITTER`),
+ * so it can decide between chords or paths of otherwise-equal cost but never
+ * overrides melody fit or functional flow. For a well-determined melody the
+ * result is identical across seeds; the same seed always yields the same result.
+ *
+ * @param opts The melody and, optionally, the generation context, key, harmonic
+ *   rhythm, reharmonization strength, placement search, meter, and seed. Only
+ *   `melody` is required.
+ * @returns The chosen transpose, key, chord path, and per-note roles.
+ * @example
+ * ```ts
+ * import { harmonizeMelody } from '@libraz/libcantus';
+ * const result = harmonizeMelody({
+ *   melody: [
+ *     { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *     { pitch: 64, startBeat: 1, durationBeat: 1 },
+ *   ],
+ * });
+ * result.chords; // one ChordSpan per chord change, on the harmonic-rhythm grid
+ * ```
+ * @category Reharmonization
+ */
+declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
 
-export { Articulation, BASS_LICKS, type BassLick, ChordLike, ChordSegment, type ClassifiedMelodyTone, DRUM_KIT, DRUM_PATTERNS, DrumHit, type DrumPattern, type DrumPatternOptions, type DrumStroke, DrumStyle, type DrumVocabulary, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, type FillArchetype, type FillStroke, type FillType, type FillVelocity, GenerationContextInput, Genre, GridEvent, GrooveFeel, type ImitationAnswer, type ImitationOptions, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, type KickFigure, type KickPattern, type KickSlot, type LickMaterial, type LickNote, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, type MelodyToneRole, NoteEvent, PercussionProfile, type PlaceLicksOptions, Section, StringedProfile, TimeSignature, Vocabulary, classifyMelodyTones, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, sustainsShift, sustainsStrokes };
+export { Articulation, BASS_LICKS, type BassLick, ChordLike, ChordSegment, type ClassifiedMelodyTone, DRUM_KIT, DRUM_PATTERNS, DrumHit, type DrumPattern, type DrumPatternOptions, type DrumStroke, DrumStyle, type DrumVocabulary, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, type FillArchetype, type FillStroke, type FillType, type FillVelocity, GenerationContextInput, Genre, GridEvent, GrooveFeel, HarmonizeOptions, HarmonizeResult, type ImitationAnswer, type ImitationOptions, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, type KickFigure, type KickPattern, type KickSlot, type LickMaterial, type LickNote, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, type MelodyToneRole, MeterLike, NoteEvent, PercussionProfile, type PlaceLicksOptions, Section, StringedProfile, Vocabulary, classifyMelodyTones, harmonizeMelody, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, sustainsShift, sustainsStrokes };