@libraz/libcantus 0.9.3 → 0.9.5

package/dist/generate/index.d.cts

@@ -1,9 +1,10 @@
-import { T as TimeSignature } from '../index-Cl7mhOFM.cjs';
-import { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.cjs';
-import { C as Chord, a as ChordQuality, b as ChordSpan } from '../index-BNlGP86A.cjs';
-import { H as HarmonyRole } from '../index-Dikst44v.cjs';
-import { b as ChordTimeline } from '../index-CpOsP1y9.cjs';
-import { B as BorrowedSource, H as HarmonicFunction } from '../function-DYt4iKsn.cjs';
+import { B as BorrowedSource, H as HarmonicFunction } from '../function-CxixTB02.cjs';
+import { K as KeyScale, N as NoteEvent } from '../types-BN6_Q9Kl.cjs';
+import { b as ChordSegment, C as Chord, a as ChordQuality, c as ChordSpan } from '../index-oTQbYYIs.cjs';
+export { d as ChordToneRole, P as PitchSpelling } from '../index-oTQbYYIs.cjs';
+import { a as ChordTimeline } from '../index-BkYJ0xMq.cjs';
+import { T as TimeSignature } from '../index-DXd9JikN.cjs';
+import { H as HarmonyRole } from '../index-x2vcsduE.cjs';
 
 /**
  * Deterministic bass-line generation over a chord placement.
@@ -22,19 +23,24 @@ import { B as BorrowedSource, H as HarmonicFunction } from '../function-DYt4iKsn
 /**
  * A chord sounding over a half-open beat span `[startBeat, endBeat)`.
  *
+ * The same record {@link ChordSegment} names, so a timeline segment can be fed
+ * straight to the bass generator.
+ *
  * @category Composition
  */
-type BassSegment = {
-    startBeat: number;
-    endBeat: number;
-    chord: Chord;
-};
+type BassSegment = ChordSegment;
+/**
+ * Every bass-line idiom, in declaration order.
+ *
+ * @category Composition
+ */
+declare const BASS_STYLES: readonly ["root", "rootFifth", "pop", "walking", "arpeggio"];
 /**
  * The bass-line idiom to generate.
  *
  * @category Composition
  */
-type BassStyle = 'root' | 'rootFifth' | 'pop' | 'walking' | 'arpeggio';
+type BassStyle = (typeof BASS_STYLES)[number];
 /**
  * Options controlling {@link generateBassLine}.
  *
@@ -42,7 +48,7 @@ type BassStyle = 'root' | 'rootFifth' | 'pop' | 'walking' | 'arpeggio';
  */
 type BassLineOptions = {
     /** Chord placement to follow; need not be pre-sorted. */
-    segments: BassSegment[];
+    segments: readonly BassSegment[];
     /** Key/scale context, used for diatonic approach tones in `walking`. */
     key: KeyScale;
     /**
@@ -59,6 +65,8 @@ type BassLineOptions = {
     style?: BassStyle;
     /**
      * Target register as a base MIDI octave; roots land around `octave*12+12`.
+     * An octave pickup in the `pop` style may drop a note into the octave below
+     * that band, which is where such a pickup belongs.
      *
      * @defaultValue 2
      */
@@ -102,13 +110,28 @@ declare function generateBassLine(opts: BassLineOptions): NoteEvent[];
  */
 type CounterMelodyOptions = {
     /** The lead line to write against, in ascending onset order. */
-    melody: NoteEvent[];
-    /** Chord sounding at an absolute beat position, or null when none applies. */
-    chordAt: (beat: number) => Chord | null;
+    melody: readonly NoteEvent[];
+    /**
+     * The harmony to write against. A timeline carries its own segment
+     * boundaries, so a chord change anywhere — including off the generator's
+     * half-beat probe grid — is seen; prefer it over `chordAt`.
+     *
+     * Exactly one of `timeline` and `chordAt` is required; `timeline` wins when
+     * both are given.
+     */
+    timeline?: ChordTimeline;
+    /**
+     * Chord sounding at an absolute beat position, or null when none applies.
+     *
+     * A callback is opaque: the generator cannot see where it changes, so it
+     * probes a half-beat grid and otherwise relies on `chordChangeBeats`. A held
+     * counter note that spans an unseen change is not checked against the new
+     * chord.
+     */
+    chordAt?: (beat: number) => Chord | null;
     /**
-     * Exact chord-change beats exposed by the caller's timeline. The generator
-     * also probes its half-beat grid, but callback discontinuities between grid
-     * points are not introspectable and should be listed here.
+     * Exact chord-change beats the `chordAt` callback does not expose. Ignored
+     * when `timeline` is given, since a timeline lists its own boundaries.
      */
     chordChangeBeats?: number[];
     /** Key/scale context for scale-tone decisions. */
@@ -143,7 +166,11 @@ type CounterMelodyOptions = {
     /** Highest MIDI pitch the counter line may use (default derived from `register`). */
     pitchHigh?: number;
     /**
-     * PRNG seed; the same seed always yields the same line.
+     * PRNG seed. It places the `'complement'` onsets and breaks ties between
+     * equally good candidate pitches; the same seed always yields the same line.
+     * Where the constraints leave only one good answer — which is common with
+     * `rhythm: 'follow'`, whose onsets are fixed by the melody — changing the seed
+     * changes nothing.
      *
      * @defaultValue 0
      */
@@ -159,8 +186,10 @@ type CounterMelodyOptions = {
  * consonant tensions against the sounding melody note), rejecting candidates
  * that would form a parallel perfect interval with the melody or sit on the
  * wrong side of it, then scored to favour contrary or oblique motion, imperfect
- * consonance, and stepwise movement. Ties break toward the lower pitch, so a
- * given seed always yields the same line. Notes extend to the next counter
+ * consonance, and stepwise movement. Ties are broken by a seeded perturbation far
+ * below any real score difference (see `TIE_BREAK_JITTER`), so the same
+ * seed always yields the same line while a different seed can only reshuffle
+ * candidates that were already equally good. Notes extend to the next counter
  * onset (the last to the melody's end) at a velocity slightly under the melody.
  *
  * @param opts The lead line, chord context callback, key, and generation knobs.
@@ -179,22 +208,92 @@ type CounterMelodyOptions = {
  */
 declare function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[];
 
-/** A single percussion onset. */
+/**
+ * The percussion voices the generator emits, as General MIDI note numbers.
+ *
+ * A {@link DrumHit} carries only its pitch, so splitting a kit across tracks —
+ * kick to one, snare to another — means comparing against these numbers. They
+ * are published so that comparison is a named constant covered by semver
+ * rather than a hard-coded 36.
+ *
+ * @example
+ * ```ts
+ * import { DRUM_NOTES, generateDrums } from '@libraz/libcantus';
+ * const hits = generateDrums({ bars: 1, bpm: 120, style: 'standard', section: 'verse', density: 0.5 });
+ * const kick = hits.filter((hit) => hit.pitch === DRUM_NOTES.kick);
+ * ```
+ * @category Composition
+ */
+declare const DRUM_NOTES: Readonly<{
+    readonly kick: 36;
+    readonly snare: 38;
+    readonly sideStick: 37;
+    readonly handClap: 39;
+    readonly closedHiHat: 42;
+    readonly pedalHiHat: 44;
+    readonly openHiHat: 46;
+    readonly crash: 49;
+    readonly ride: 51;
+    readonly tambourine: 54;
+    readonly highTom: 50;
+    readonly midTom: 47;
+    readonly lowTom: 45;
+    readonly shaker: 82;
+}>;
+/**
+ * A percussion voice name, one key of {@link DRUM_NOTES}.
+ *
+ * @category Composition
+ */
+type DrumVoice = keyof typeof DRUM_NOTES;
+/**
+ * The voice a percussion note number names.
+ *
+ * @param pitch The General MIDI note number.
+ * @returns The voice, or undefined for a note this generator never emits.
+ * @category Composition
+ */
+declare function drumVoiceOf(pitch: number): DrumVoice | undefined;
+/**
+ * A single percussion onset.
+ *
+ * @category Composition
+ */
 type DrumHit = {
+    /** General MIDI note number; {@link drumVoiceOf} names it. */
     pitch: number;
     startBeat: number;
     durationBeat: number;
     velocity: number;
 };
 
+/** Every groove feel, in declaration order. */
+declare const DRUM_FEELS: readonly ["straight", "swing", "shuffle"];
 /** Groove feel controlling off-beat swing. */
-type Feel = 'straight' | 'swing' | 'shuffle';
-/** Public groove style identifiers. */
-type GrooveStyle = 'standard' | 'funk' | 'shuffle' | 'bossa' | 'trap' | 'halftime' | 'breakbeat' | 'house' | 'synthpop';
-/** Public role identifiers gating which voices are present. */
-type DrumRole = 'full' | 'ambient' | 'minimal' | 'fxOnly';
+type Feel = (typeof DRUM_FEELS)[number];
+/**
+ * Every public groove style, in declaration order. The type is derived from
+ * this list so the runtime guard and the type can never disagree.
+ */
+declare const GROOVE_STYLES: readonly ["standard", "funk", "shuffle", "bossa", "trap", "halftime", "breakbeat", "house", "synthpop"];
+/**
+ * Public groove style identifiers.
+ *
+ * @category Composition
+ */
+type GrooveStyle = (typeof GROOVE_STYLES)[number];
+/** Every public role, in declaration order. */
+declare const DRUM_ROLES: readonly ["full", "ambient", "minimal", "fxOnly"];
+/**
+ * Public role identifiers gating which voices are present.
+ *
+ * @category Composition
+ */
+type DrumRole = (typeof DRUM_ROLES)[number];
+/** Every public section, in declaration order. */
+declare const PUBLIC_SECTIONS: readonly ["intro", "verse", "prechorus", "chorus", "bridge", "outro"];
 /** Public section identifiers. */
-type PublicSection = 'intro' | 'verse' | 'prechorus' | 'chorus' | 'bridge' | 'outro';
+type PublicSection = (typeof PUBLIC_SECTIONS)[number];
 
 /**
  * Groove feel (the swing/straight rhythmic character) for {@link generateDrums}.
@@ -236,20 +335,40 @@ type EuclideanKick = {
  * @category Composition
  */
 type DrumsOptions = {
+    /**
+     * Number of bars to generate.
+     */
     bars: number;
     bpm: number;
     style: GrooveStyle;
     section: Section;
     density: number;
+    /** Time signature; defaults to 4/4. */
+    ts?: TimeSignature;
     /**
      * Replace the final bar with a fill.
      *
+     * A pre-chorus leading into a chorus builds instead: the two-bar lift takes
+     * precedence over the fill, since the buildup already marks the phrase end.
+     * Set `nextSection` to anything but `'chorus'` to get the fill.
+     *
      * @defaultValue false
      */
     fills?: boolean;
     feel?: GrooveFeel;
     /**
-     * Voicing role; `'fxOnly'` suppresses the main kick/snare/ghost/fill voices.
+     * Voicing role, from busiest to sparsest:
+     *
+     * - `'full'`: every voice, backbeat snare at full weight.
+     * - `'ambient'`: side-stick backbeat, ride instead of hi-hat.
+     * - `'minimal'`: side-stick backbeat quieter still, pedal hi-hat, no
+     *   auxiliary percussion.
+     * - `'fxOnly'`: no kick, snare, ghost notes, timekeeping hi-hat, or fills —
+     *   only the fx and auxiliary voices.
+     *
+     * Roles express orchestration priority and peak dynamics, not a strict hit
+     * count: style-specific ride, foot-hi-hat, and auxiliary patterns may make a
+     * sparser role emit more individual onsets in a particular bar.
      *
      * @defaultValue `'full'`
      */
@@ -286,8 +405,12 @@ type DrumsOptions = {
  * overrides the kick with an evenly-spread Euclidean pattern. Output is fully
  * determined by the options plus `seed`.
  *
+ * The patterns are 4/4 only — backbeats, hi-hat subdivisions, and fills are all
+ * written against a four-beat bar — so beat positions are quarter notes and bar
+ * `n` starts at beat `4n`.
+ *
  * @param opts Generation options.
- * @returns Percussion onsets in bar order.
+ * @returns Percussion onsets in onset order, ties broken by pitch.
  *
  * @example
  * ```ts
@@ -377,9 +500,12 @@ type HumanizeOptions = {
  * const events = [{ pitch: 60, startBeat: 0, durationBeat: 1, velocity: 80 }];
  * humanize(events, { seed: 1, timing: 0.03 }); // copies with jittered timing and accented velocity
  * ```
+ * Notes with a zero or negative duration never sound and are dropped, so the
+ * result can be shorter than the input.
+ *
  * @category Rhythm & Meter
  */
-declare function humanize(events: NoteEvent[], opts?: HumanizeOptions): NoteEvent[];
+declare function humanize(events: readonly NoteEvent[], opts?: HumanizeOptions): NoteEvent[];
 /**
  * The recorded feel at a single grid slot: an average timing deviation and velocity.
  *
@@ -426,10 +552,12 @@ type GrooveTemplate = {
  * @param events The (typically "groovy", human-played) events to analyze.
  * @param ts The time signature, used to compute the bar length.
  * @param subdivision Grid resolution: equal grid steps per quarter-note beat.
+ *   Defaults to a sixteenth-note grid, which is where the timing deviations a
+ *   template records — swing, push, drag — are audible.
  * @returns The extracted groove template.
  * @category Rhythm & Meter
  */
-declare function extractGrooveTemplate(events: NoteEvent[], ts: TimeSignature, subdivision: number): GrooveTemplate;
+declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: TimeSignature, subdivision?: number): GrooveTemplate;
 /**
  * Apply a groove template to a set of (typically quantized) note events: each
  * event is snapped to its grid slot and then offset by that slot's recorded
@@ -437,6 +565,8 @@ declare function extractGrooveTemplate(events: NoteEvent[], ts: TimeSignature, s
  * Velocity is set to the slot's recorded average when it recorded one (a
  * non-`null` velocity, including a genuine 0); otherwise the event's own
  * velocity is left untouched.
+ * Non-positive-duration input artefacts are omitted, so output positions do
+ * not retain a one-to-one correspondence with the input array.
  *
  * If the template carries a time signature (see {@link GrooveTemplate.ts}) it
  * must match `ts`, since a differing bar length would misalign the per-bar
@@ -464,7 +594,7 @@ declare function extractGrooveTemplate(events: NoteEvent[], ts: TimeSignature, s
  * ```
  * @category Rhythm & Meter
  */
-declare function applyGrooveTemplate(events: NoteEvent[], template: GrooveTemplate, ts: TimeSignature): NoteEvent[];
+declare function applyGrooveTemplate(events: readonly NoteEvent[], template: GrooveTemplate, ts: TimeSignature): NoteEvent[];
 
 /**
  * Broad production style a progression preset suits.
@@ -486,10 +616,56 @@ type ProgFunction = 'loop' | 'tensionBuild' | 'cadenceStrong' | 'stable';
 type ProgressionPreset = {
     id: string;
     name: string;
-    degrees: number[];
+    /**
+     * The chord roots, in order, as {@link ProgressionDegree} codes: 0..6 for the
+     * key's own scale degrees and {@link BORROWED_DEGREES} for the borrowed ones.
+     */
+    degrees: ProgressionDegree[];
     functional: ProgFunction;
     styles: ProgStyle[];
 };
+/**
+ * The borrowed (non-diatonic) chord roots a preset can name, as their semitone
+ * code for a borrowed degree. These are stable identifiers, not semitone
+ * offsets: their pitch-class offsets are resolved internally.
+ *
+ * Scale degrees 0..6 address the key's own chords; these codes continue the
+ * numbering for the chromatic chords a pop progression borrows, so a preset is
+ * one flat list of degree codes.
+ *
+ * @example
+ * ```ts
+ * import { BORROWED_DEGREES, generateProgression, majorKey } from '@libraz/libcantus';
+ * generateProgression({
+ *   key: majorKey(0),
+ *   style: 'rock',
+ *   bars: 4,
+ *   preset: { degrees: [0, BORROWED_DEGREES.bVII, 3, 0] },
+ * });
+ * ```
+ * @category Composition
+ */
+declare const BORROWED_DEGREES: Readonly<{
+    /** Flat submediant: bVI. */
+    readonly bVI: 8;
+    /** Flat subtonic: bVII. */
+    readonly bVII: 10;
+    /** Flat mediant: bIII. */
+    readonly bIII: 11;
+    /** Minor subdominant borrowed from the parallel minor: iv. */
+    readonly iv: 12;
+    /** Neapolitan: bII. */
+    readonly bII: 13;
+    /** Sharp subdominant, the diminished #IV. */
+    readonly sharpIV: 14;
+}>;
+/**
+ * A chord root in a preset: a scale degree 0..6, or one of
+ * {@link BORROWED_DEGREES}.
+ *
+ * @category Composition
+ */
+type ProgressionDegree = number;
 /**
  * Options controlling {@link generateProgression}.
  *
@@ -497,9 +673,21 @@ type ProgressionPreset = {
  */
 type ProgressionOptions = {
     key: KeyScale;
+    /**
+     * Which pool of built-in presets to choose from. Ignored when `preset` names
+     * the progression outright.
+     */
     style: ProgStyle;
     bars: number;
+    /** Pick a specific built-in preset by id instead of choosing one by style. */
     presetId?: string;
+    /**
+     * Use this progression rather than a built-in one. Only `degrees` is
+     * required; see {@link BORROWED_DEGREES} for the non-diatonic codes.
+     */
+    preset?: Partial<ProgressionPreset> & {
+        degrees: ProgressionDegree[];
+    };
     ext?: ChordQuality | 'auto';
     reharmonize?: boolean;
     /**
@@ -521,23 +709,44 @@ declare function progressions(): ProgressionPreset[];
  * @category Composition
  */
 declare function progressionsByStyle(style: ProgStyle): ProgressionPreset[];
+/**
+ * The preset {@link generateProgression} would choose for a style and seed.
+ *
+ * The choice is otherwise invisible: the generator returns chords, not the
+ * preset it drew them from, so a caller who wants to show or reproduce it has
+ * no way to name it.
+ *
+ * @param style The style pool to choose from.
+ * @param seed The same seed the generator would be given.
+ * @returns The preset that seed selects.
+ * @throws If no preset claims the style.
+ * @example
+ * ```ts
+ * import { pickProgressionPreset } from '@libraz/libcantus';
+ * pickProgressionPreset('dance', 3).name;
+ * ```
+ * @category Composition
+ */
+declare function pickProgressionPreset(style: ProgStyle, seed?: number): ProgressionPreset;
 /**
  * Generate a chord progression laid out one chord per bar.
  *
  * A preset is chosen by `presetId` when given, otherwise deterministically from
- * the presets matching `style`, seeded by `seed`. An unknown `presetId` is a
- * caller error and throws rather than silently falling back to a random preset.
- * The preset's degrees cycle to
+ * the presets matching `style`, seeded by `seed`. An unknown `presetId`, or a
+ * `style` no preset claims, is a caller error and throws rather than silently
+ * falling back to a random preset. The preset's degrees cycle to
  * fill `bars`; each bar is four beats, so `startBeat` is `barIndex * 4`. Chord
  * roots come from the key's diatonic scale-degree mapping. When `ext` is
  * omitted or `'auto'`, each chord takes its diatonic triad quality; otherwise
- * `ext` is forced on every chord. When `reharmonize` is set, some chords are
+ * `ext` is forced on every chord — except a chord replaced by `reharmonize`,
+ * which is a secondary dominant and is therefore always a `dom7`; those carry
+ * `secondaryDominant: true`. When `reharmonize` is set, some chords are
  * deterministically replaced with the secondary dominant (V7) of the following
  * chord, flagged with `secondaryDominant`.
  *
  * @param opts Generation options.
  * @returns One chord per bar in timeline order.
- * @throws If `presetId` is given but does not match any built-in preset.
+ * @throws If `presetId` matches no built-in preset, or `style` matches none.
  *
  * @example
  * ```ts
@@ -561,15 +770,72 @@ type MelodyNote = NoteEvent;
  *
  * @category Reharmonization
  */
+type HarmonizePlacement = {
+    /**
+     * Search a range of transpositions and keep the best-fitting one. The result
+     * reports the shift it chose in `transposeSemitones`.
+     *
+     * @defaultValue false
+     */
+    transposeSearch: boolean;
+    /**
+     * Search octave placements as well, so a melody written too high or too low
+     * is moved into a comfortable register.
+     *
+     * @defaultValue false
+     */
+    octaveSearch: boolean;
+};
+/**
+ * Options controlling {@link harmonizeMelody}.
+ *
+ * Only `melody` is required; every other knob has the default a first call
+ * wants.
+ *
+ * @category Reharmonization
+ */
 type HarmonizeOptions = {
-    melody: MelodyNote[];
-    key: KeyScale | 'infer';
-    harmonicRhythm: number;
-    reharmonize: 'diatonic' | 'secondaryDominant' | 'borrowed';
-    placement: {
-        transposeSearch: boolean;
-        octaveSearch: boolean;
-    };
+    /** The melody to harmonize, in ascending onset order. */
+    melody: readonly MelodyNote[];
+    /**
+     * The key to harmonize in, or `'infer'` to estimate it from the melody's
+     * pitch-class weighting — which is what a caller who has only a melody
+     * wants, and so the default.
+     *
+     * @defaultValue `'infer'`
+     */
+    key?: KeyScale | 'infer';
+    /**
+     * Length of each chord slot in beats. Any positive value is honoured, as in
+     * {@link chordTimelineFromNotes}; a value fine enough to make the search
+     * explode is rejected by the generation budget rather than rounded up.
+     *
+     * @defaultValue 2
+     */
+    harmonicRhythm?: number;
+    /**
+     * Time signature used to weight metric accents; defaults to 4/4. A waltz or
+     * a jig harmonized against a 4/4 accent grid gets its chords placed on the
+     * wrong beats, and the error accumulates bar by bar.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: TimeSignature;
+    /**
+     * How far beyond the key's own triads the chord vocabulary reaches:
+     * `'diatonic'` uses only them, `'secondaryDominant'` adds the dominants that
+     * tonicize each degree, and `'borrowed'` adds the parallel mode's chords too.
+     *
+     * @defaultValue `'diatonic'`
+     */
+    reharmonize?: 'diatonic' | 'secondaryDominant' | 'borrowed';
+    /**
+     * Whether to search transpositions and octave placements for the melody.
+     * Both are off by default, so the melody is harmonized where it was written.
+     *
+     * @defaultValue both false
+     */
+    placement?: HarmonizePlacement;
     /**
      * Seed for the deterministic tie-break perturbation.
      *
@@ -603,26 +869,23 @@ type HarmonizeResult = {
  * ties toward placements that keep the melody in a comfortable register.
  *
  * The `seed` drives a deterministic tie-break only: it perturbs candidates by a
- * magnitude far below any real cost difference (see {@link TIE_BREAK_JITTER}),
+ * 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 Melody, key (or `'infer'`), harmonic rhythm, reharmonization
- *   strength, height-search flags, and seed.
+ * @param opts The melody and, optionally, the 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, majorKey } from '@libraz/libcantus';
+ * import { harmonizeMelody } from '@libraz/libcantus';
  * const result = harmonizeMelody({
  *   melody: [
  *     { pitch: 60, startBeat: 0, durationBeat: 1 },
  *     { pitch: 64, startBeat: 1, durationBeat: 1 },
  *   ],
- *   key: majorKey(0),
- *   harmonicRhythm: 1,
- *   reharmonize: 'diatonic',
- *   placement: { transposeSearch: false, octaveSearch: false },
  * });
  * result.chords; // one ChordSpan per harmonic-rhythm segment
  * ```
@@ -668,7 +931,15 @@ type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
 type MotifOptions = {
     key: KeyScale;
     chord?: Chord | null;
+    /** Length of the motif in bars of `ts`. */
     bars: number;
+    /**
+     * Meter the bars are counted in. It sets the bar length, so a motif shares a
+     * bar grid with the other generators instead of assuming four beats.
+     *
+     * @defaultValue 4/4
+     */
+    ts?: TimeSignature;
     /**
      * Melodic contour shape the line follows.
      *
@@ -713,6 +984,23 @@ type MotifOptions = {
  * @category Composition
  */
 declare function generateMotif(opts: MotifOptions): MotifCell;
+/**
+ * Turn a motif cell into note events.
+ *
+ * A {@link MotifNote} already carries the {@link NoteEvent} fields, but a cell
+ * wraps them in an object; this unwraps it, so a motif can be humanized,
+ * grooved, or written out like any other line.
+ *
+ * @param cell The motif to convert.
+ * @returns The cell's notes, copied, in the order they are stored.
+ * @example
+ * ```ts
+ * import { generateMotif, humanize, majorKey, motifToNoteEvents } from '@libraz/libcantus';
+ * humanize(motifToNoteEvents(generateMotif({ key: majorKey(0), bars: 2 })));
+ * ```
+ * @category Composition
+ */
+declare function motifToNoteEvents(cell: MotifCell): NoteEvent[];
 /**
  * Apply a transformation to a motif cell.
  *
@@ -731,6 +1019,7 @@ declare function generateMotif(opts: MotifOptions): MotifCell;
  * @param key Key context for the diatonic transforms; without it,
  *   `transposeDiatonic` and `sequence` shift chromatically by semitones.
  * @returns The transformed cell.
+ * @throws If a transformed pitch would fall outside the MIDI range 0..127.
  *
  * @example
  * ```ts
@@ -752,7 +1041,8 @@ declare function transformMotif(cell: MotifCell, t: MotifTransform, amount?: num
  * @param cell The source motif.
  * @param timeline Chord segments to snap against.
  * @param key Key context (used to keep snapped pitches sensible).
- * @param bars Number of four-beat bars to fill.
+ * @param bars Number of bars to fill.
+ * @param ts Meter the bars are counted in; defaults to 4/4.
  * @returns The developed, harmony-aware cell.
  *
  * @example
@@ -765,7 +1055,7 @@ declare function transformMotif(cell: MotifCell, t: MotifTransform, amount?: num
  *
  * @category Composition
  */
-declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: KeyScale, bars: number): MotifCell;
+declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: KeyScale, bars: number, ts?: TimeSignature): MotifCell;
 
 /**
  * Reharmonization: chord substitution, modal-interchange palettes, and negative
@@ -781,7 +1071,7 @@ declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: Key
  *
  * @category Reharmonization
  */
-type SubstitutionType = 'tritone' | 'relative' | 'borrowed' | 'chromatic-mediant' | 'secondary-dominant';
+type SubstitutionType = 'tritone' | 'relative' | 'borrowed' | 'chromaticMediant' | 'secondaryDominant';
 /**
  * A proposed chord substitution with its relationship, numeral, and function.
  *
@@ -813,11 +1103,9 @@ type SubstituteOptions = {
  * original chord and each other:
  *
  * - `tritone`: for a dominant-type chord, the dominant seventh a tritone away.
- * - `secondary-dominant`: for a stable target, the dominant seventh a fifth
- *   above its root (tonicizing it).
  * - `relative`: a diatonic triad a third away that shares two common tones.
  * - `borrowed`: a triad from the parallel mode with the same harmonic function.
- * - `chromatic-mediant`: a major/minor triad a third away sharing one common
+ * - `chromaticMediant`: a major/minor triad a third away sharing one common
  *   tone.
  *
  * Each result carries its Roman numeral and harmonic function in `key`. When
@@ -906,6 +1194,27 @@ type RhythmEvent = {
     /** Duration in quarter-note beats, extending to the next onset. */
     duration: number;
 };
+/**
+ * Turn rhythm events into note events at a fixed pitch.
+ *
+ * {@link RhythmEvent} names its fields `position`/`duration` because a rhythm
+ * has no pitch; every other generator in the library speaks {@link NoteEvent}.
+ * This is the bridge, so a generated rhythm can be humanized, grooved, or
+ * written out like any other line.
+ *
+ * @param events The rhythm events to convert.
+ * @param pitch The MIDI pitch to give every note.
+ * @param velocity Velocity for every note; defaults to a mezzo-forte 96.
+ * @returns The note events, in the order given.
+ * @example
+ * ```ts
+ * import { generateRhythm, humanize, rhythmToNoteEvents } from '@libraz/libcantus';
+ * const rhythm = generateRhythm({ numerator: 4, denominator: 4 }, { bars: 2 });
+ * humanize(rhythmToNoteEvents(rhythm, 38));
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function rhythmToNoteEvents(events: RhythmEvent[], pitch: number, velocity?: number): NoteEvent[];
 /**
  * Options controlling {@link generateRhythm}.
  *
@@ -934,8 +1243,7 @@ type RhythmOptions = {
     subdivision?: number;
     /**
      * Overall onset density in [0, 1]. Scales the per-slot onset probability, so
-     * higher values fill more grid slots. Values outside [0, 1] are clamped into
-     * range.
+     * higher values fill more grid slots. Values outside [0, 1] are rejected.
      *
      * @defaultValue 0.5
      */
@@ -959,7 +1267,7 @@ declare function onsetWeightCurve(weight: number): number;
  * and sampled from the seeded PRNG. Every bar's downbeat is always an onset, so
  * a pattern of any length has a reliable pulse independent of the seed. Each
  * event's duration extends to the next onset, and the last event extends to the
- * end of the span. `density` is clamped to [0, 1].
+ * end of the span. `density` must be in [0, 1].
  *
  * @param ts The time signature.
  * @param opts Generation options.
@@ -983,4 +1291,4 @@ declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): Rhythm
  */
 declare function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number;
 
-export { type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, type CounterMelodyOptions, type DrumHit, type DrumRole, type DrumsOptions, type EuclideanKick, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, type HarmonizeOptions, type HarmonizeResult, type HumanizeOptions, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifOptions, type MotifTransform, type ProgFunction, type ProgStyle, type ProgressionOptions, type ProgressionPreset, type RhythmEvent, type RhythmOptions, type Section, type SubstituteOptions, type Substitution, type SubstitutionType, applyGrooveTemplate, developMotif, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, negativeHarmonyMirror, onsetWeightCurve, progressions, progressionsByStyle, rhythmDensity, substituteChord, transformMotif };
+export { BASS_STYLES, BORROWED_DEGREES, type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, BorrowedSource, Chord as ChordData, ChordQuality, ChordSegment, ChordSpan, ChordTimeline, type CounterMelodyOptions, DRUM_NOTES, type DrumHit, type DrumRole, type DrumVoice, type DrumsOptions, type EuclideanKick, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, HarmonicFunction, type HarmonizeOptions, type HarmonizePlacement, type HarmonizeResult, HarmonyRole, type HumanizeOptions, KeyScale, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifOptions, type MotifTransform, NoteEvent, type ProgFunction, type ProgStyle, type ProgressionDegree, type ProgressionOptions, type ProgressionPreset, type RhythmEvent, type RhythmOptions, type Section, type SubstituteOptions, type Substitution, type SubstitutionType, TimeSignature, applyGrooveTemplate, developMotif, drumVoiceOf, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, motifToNoteEvents, negativeHarmonyMirror, onsetWeightCurve, pickProgressionPreset, progressions, progressionsByStyle, rhythmDensity, rhythmToNoteEvents, substituteChord, transformMotif };