@libraz/libcantus 0.9.1 → 0.9.3

package/dist/generate/index.d.ts

@@ -0,0 +1,986 @@
+import { T as TimeSignature } from '../index-Cl7mhOFM.js';
+import { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.js';
+import { C as Chord, a as ChordQuality, b as ChordSpan } from '../index-Bt4tOUD9.js';
+import { H as HarmonyRole } from '../index-Bg5dYMmZ.js';
+import { b as ChordTimeline } from '../index-DxvARIP2.js';
+import { B as BorrowedSource, H as HarmonicFunction } from '../function-DVH4Eusr.js';
+
+/**
+ * Deterministic bass-line generation over a chord placement.
+ *
+ * Given a sequence of chord segments and a key, this builds a monophonic bass
+ * line in a chosen low register. Several idiomatic styles are supported, from a
+ * single held root per segment to a quarter-note walking line that leads by
+ * step into each chord change. All pitches are kept in a narrow bass band and
+ * consecutive notes move by small intervals; given a seed the output is fully
+ * reproducible.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the
+ * library-wide convention.
+ */
+
+/**
+ * A chord sounding over a half-open beat span `[startBeat, endBeat)`.
+ *
+ * @category Composition
+ */
+type BassSegment = {
+    startBeat: number;
+    endBeat: number;
+    chord: Chord;
+};
+/**
+ * The bass-line idiom to generate.
+ *
+ * @category Composition
+ */
+type BassStyle = 'root' | 'rootFifth' | 'pop' | 'walking' | 'arpeggio';
+/**
+ * Options controlling {@link generateBassLine}.
+ *
+ * @category Composition
+ */
+type BassLineOptions = {
+    /** Chord placement to follow; need not be pre-sorted. */
+    segments: BassSegment[];
+    /** Key/scale context, used for diatonic approach tones in `walking`. */
+    key: KeyScale;
+    /**
+     * Time signature; used for metric accents.
+     *
+     * @defaultValue `{ numerator: 4, denominator: 4 }`
+     */
+    ts?: TimeSignature;
+    /**
+     * Bass-line idiom.
+     *
+     * @defaultValue `'root'`
+     */
+    style?: BassStyle;
+    /**
+     * Target register as a base MIDI octave; roots land around `octave*12+12`.
+     *
+     * @defaultValue 2
+     */
+    octave?: number;
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
+    seed?: number;
+};
+/**
+ * Generate a bass line following a chord placement.
+ *
+ * Each segment contributes notes in the chosen bass register per the selected
+ * style; consecutive notes are kept within roughly a fifth. Every note's
+ * duration extends to the next onset (the final note extends to the last
+ * segment's end). Given a seed the output is fully reproducible.
+ *
+ * @param opts Segments, key, and generation options.
+ * @returns Bass notes sorted by onset, non-overlapping.
+ *
+ * @example
+ * ```ts
+ * import { generateBassLine, makeChord, majorKey } from '@libraz/libcantus';
+ * const segments = [
+ *   { startBeat: 0, endBeat: 4, chord: makeChord(0, 'maj') },
+ *   { startBeat: 4, endBeat: 8, chord: makeChord(7, 'maj') },
+ * ];
+ * const notes = generateBassLine({ segments, key: majorKey(0), style: 'walking' });
+ * ```
+ *
+ * @category Composition
+ */
+declare function generateBassLine(opts: BassLineOptions): NoteEvent[];
+
+/**
+ * Options controlling {@link generateCounterMelody}.
+ *
+ * @category Voicing & Counterpoint
+ */
+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;
+    /**
+     * 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.
+     */
+    chordChangeBeats?: number[];
+    /** Key/scale context for scale-tone decisions. */
+    key: KeyScale;
+    /**
+     * Meter used for strong-beat decisions.
+     *
+     * @defaultValue 4/4
+     */
+    ts?: TimeSignature;
+    /**
+     * Which side of the melody the counter line occupies.
+     *
+     * @defaultValue 'below'
+     */
+    register?: 'above' | 'below';
+    /**
+     * Onset strategy: `'complement'` moves where the melody holds or rests and
+     * reinforces some strong beats; `'follow'` mirrors melody onsets.
+     *
+     * @defaultValue 'complement'
+     */
+    rhythm?: 'complement' | 'follow';
+    /**
+     * Safety profile applied to candidate pitches.
+     *
+     * @defaultValue 'pop'
+     */
+    profile?: 'strict' | 'pop';
+    /** Lowest MIDI pitch the counter line may use (default derived from `register`). */
+    pitchLow?: number;
+    /** Highest MIDI pitch the counter line may use (default derived from `register`). */
+    pitchHigh?: number;
+    /**
+     * PRNG seed; the same seed always yields the same line.
+     *
+     * @defaultValue 0
+     */
+    seed?: number;
+};
+/**
+ * Generate a counter melody against a lead line.
+ *
+ * Onsets are chosen per `rhythm`: `'follow'` places one counter note on each
+ * melody onset; `'complement'` fills melody rests and sustains and reinforces
+ * an occasional strong beat, spaced at least a beat apart. Each onset's pitch
+ * is picked from the safe pitches in the counter register (chord tones and
+ * 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
+ * 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.
+ * @returns The counter line as note events sorted by onset; `[]` for an empty melody.
+ * @example
+ * ```ts
+ * import { generateCounterMelody, majorKey, parseChordSymbol } from '@libraz/libcantus';
+ * const melody = [{ pitch: 72, startBeat: 0, durationBeat: 2 }];
+ * const counter = generateCounterMelody({
+ *   melody,
+ *   chordAt: () => parseChordSymbol('C'),
+ *   key: majorKey(0),
+ * }); // note events below the melody, in onset order
+ * ```
+ * @category Voicing & Counterpoint
+ */
+declare function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[];
+
+/** A single percussion onset. */
+type DrumHit = {
+    pitch: number;
+    startBeat: number;
+    durationBeat: number;
+    velocity: number;
+};
+
+/** 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';
+/** Public section identifiers. */
+type PublicSection = 'intro' | 'verse' | 'prechorus' | 'chorus' | 'bridge' | 'outro';
+
+/**
+ * Groove feel (the swing/straight rhythmic character) for {@link generateDrums}.
+ *
+ * @category Composition
+ */
+type GrooveFeel = Feel;
+
+/**
+ * Public section identifiers for {@link generateDrums}.
+ *
+ * @category Composition
+ */
+type Section = PublicSection;
+/**
+ * A Euclidean (Bjorklund) kick pattern for {@link generateDrums}.
+ *
+ * @category Composition
+ */
+type EuclideanKick = {
+    /** Number of kick onsets, clamped to `[0, steps]`. */
+    pulses: number;
+    /**
+     * Total steps in the bar (1..16).
+     *
+     * @defaultValue 16
+     */
+    steps?: number;
+    /**
+     * Steps to rotate the onsets toward later positions.
+     *
+     * @defaultValue 0
+     */
+    rotation?: number;
+};
+/**
+ * Options controlling {@link generateDrums}.
+ *
+ * @category Composition
+ */
+type DrumsOptions = {
+    bars: number;
+    bpm: number;
+    style: GrooveStyle;
+    section: Section;
+    density: number;
+    /**
+     * Replace the final bar with a fill.
+     *
+     * @defaultValue false
+     */
+    fills?: boolean;
+    feel?: GrooveFeel;
+    /**
+     * Voicing role; `'fxOnly'` suppresses the main kick/snare/ghost/fill voices.
+     *
+     * @defaultValue `'full'`
+     */
+    role?: DrumRole;
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
+    seed?: number;
+    /**
+     * Section the final-bar fill leads into. Shapes which fill archetype is
+     * chosen (into-chorus and out-of-intro fills differ from generic ones).
+     * Defaults to `section`, i.e. a within-section fill.
+     */
+    nextSection?: Section;
+    /**
+     * When set, the kick follows this Euclidean rhythm instead of the
+     * style/section pattern, giving direct access to evenly spread onsets.
+     */
+    euclideanKick?: EuclideanKick;
+};
+/**
+ * Generate a drum performance as a flat list of onsets.
+ *
+ * Every voice (kick, snare, ghost snares, closed/open/foot hi-hats, ride, toms,
+ * crash, and auxiliary percussion) is emitted as a {@link DrumHit} distinguished
+ * by its General MIDI pitch. Groove style selects an internal style and feel;
+ * `density` sets the backing-density level; `section` shapes kick, hi-hat, ghost,
+ * and percussion density. 16th-note hi-hats drop to 8ths at or above 150 BPM.
+ * When `fills` is true the final bar is replaced with a fill whose archetype is
+ * shaped by `nextSection`; a fill that would emit nothing on its beat falls back
+ * to the normal groove so the phrase end is never silent. `euclideanKick`
+ * overrides the kick with an evenly-spread Euclidean pattern. Output is fully
+ * determined by the options plus `seed`.
+ *
+ * @param opts Generation options.
+ * @returns Percussion onsets in bar order.
+ *
+ * @example
+ * ```ts
+ * import { generateDrums } from '@libraz/libcantus';
+ * const hits = generateDrums({ bars: 4, bpm: 120, style: 'standard', section: 'chorus', density: 0.6, fills: true });
+ * // Fully determined by the options plus seed (defaults to 0).
+ * ```
+ *
+ * @category Composition
+ */
+declare function generateDrums(opts: DrumsOptions): DrumHit[];
+
+/**
+ * Groove and humanization: nudging quantized note events toward a more human
+ * feel, and capturing/replaying the timing-and-velocity "feel" of a
+ * performance as a reusable groove template.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the
+ * library-wide convention. Randomness, where used, always goes through the
+ * seeded PRNG from the `random` module so results are fully reproducible.
+ */
+
+/**
+ * Options controlling {@link humanize}.
+ *
+ * @category Rhythm & Meter
+ */
+type HumanizeOptions = {
+    /**
+     * Time signature used to derive metric accents.
+     *
+     * @defaultValue 4/4
+     */
+    ts?: TimeSignature;
+    /**
+     * Maximum timing jitter in quarter-note beats, applied as ±this value.
+     *
+     * @defaultValue 0.02
+     */
+    timing?: number;
+    /**
+     * Maximum velocity jitter (MIDI units), applied as ±this value.
+     *
+     * @defaultValue 8
+     */
+    velocity?: number;
+    /**
+     * How much louder strong beats get relative to weak ones, in MIDI velocity units.
+     *
+     * @defaultValue 12
+     */
+    accent?: number;
+    /**
+     * Velocity assumed for events with no `velocity` of their own.
+     *
+     * @defaultValue 80
+     */
+    baseVelocity?: number;
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
+    seed?: number;
+};
+/**
+ * Humanize a sequence of note events by nudging their timing and velocity
+ * with small, deterministic (seeded) randomness plus a metric-accent shape:
+ * events on strong beats (see {@link metricWeight}) come out louder on
+ * average than events on weak ones.
+ *
+ * Each returned event is a copy; `startBeat` is jittered within
+ * `[-timing, +timing]` beats and clamped to be non-negative, and `velocity`
+ * is the event's own velocity (or `baseVelocity` if it has none) plus an
+ * accent term scaled by the event's metric weight plus a jitter within
+ * `[-velocity, +velocity]`, clamped to `[1, 127]` and rounded. The metric
+ * weight is computed from each event's original (pre-jitter) `startBeat`.
+ * `pitch` and `durationBeat` pass through unchanged, and the output keeps the
+ * input order.
+ *
+ * @param events The events to humanize.
+ * @param opts Humanization options.
+ * @returns Humanized copies of `events`, in input order.
+ * @example
+ * ```ts
+ * import { humanize } from '@libraz/libcantus';
+ * const events = [{ pitch: 60, startBeat: 0, durationBeat: 1, velocity: 80 }];
+ * humanize(events, { seed: 1, timing: 0.03 }); // copies with jittered timing and accented velocity
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function humanize(events: NoteEvent[], opts?: HumanizeOptions): NoteEvent[];
+/**
+ * The recorded feel at a single grid slot: an average timing deviation and velocity.
+ *
+ * @category Rhythm & Meter
+ */
+type GrooveSlot = {
+    /** Average `actualStartBeat - quantizedBeat` (in quarter-note beats) for events landing on this slot. */
+    timingOffset: number;
+    /**
+     * Average velocity of events landing on this slot, or `null` if no event
+     * with a velocity did. `null` (not 0) is the "unrecorded" sentinel so that a
+     * genuine velocity of 0 is preserved and applied like any other value.
+     */
+    velocity: number | null;
+};
+/**
+ * A per-bar grid of timing and velocity deviations captured from a performance.
+ *
+ * @category Rhythm & Meter
+ */
+type GrooveTemplate = {
+    /** Grid resolution: equal grid steps per quarter-note beat. */
+    subdivision: number;
+    /** Number of grid slots per bar (`beatsPerBar(ts) * subdivision`). */
+    slotsPerBar: number;
+    /** One entry per grid slot, in slot-index order (slot 0 is the downbeat). */
+    slots: GrooveSlot[];
+    /**
+     * The time signature the template was extracted under. {@link applyGrooveTemplate}
+     * requires the apply-time meter to match this so the per-bar grid lines up
+     * instead of silently drifting. Optional for backward compatibility with
+     * templates constructed without it (in which case no check is performed).
+     */
+    ts?: TimeSignature;
+};
+/**
+ * Extract a groove template from a set of note events: for each grid slot,
+ * the average timing deviation from the quantized grid and the average
+ * velocity of events landing on it. Slots with no velocity-carrying event
+ * record `velocity: null` (the "unrecorded" sentinel); empty slots default to
+ * `{ timingOffset: 0, velocity: null }`. The time signature is stored on the
+ * template so {@link applyGrooveTemplate} can verify the meter matches.
+ *
+ * @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.
+ * @returns The extracted groove template.
+ * @category Rhythm & Meter
+ */
+declare function extractGrooveTemplate(events: 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
+ * timing deviation, pushing stiff timing toward the template's feel.
+ * 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.
+ *
+ * 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
+ * grid and drift the feel; a mismatch throws rather than corrupting timing
+ * silently.
+ *
+ * @param events The events to reshape.
+ * @param template The groove template, from {@link extractGrooveTemplate}.
+ * @param ts The time signature, used to compute the bar length.
+ * @returns Reshaped copies of `events`, in input order.
+ * @throws If `template.ts` is set and does not match `ts`.
+ * @example
+ * ```ts
+ * import { extractGrooveTemplate, applyGrooveTemplate, parseTimeSignature } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * // Learn the feel from a loosely played performance...
+ * const groovy = [
+ *   { pitch: 36, startBeat: 0.02, durationBeat: 1, velocity: 100 },
+ *   { pitch: 38, startBeat: 1.06, durationBeat: 1, velocity: 70 },
+ * ];
+ * const template = extractGrooveTemplate(groovy, ts, 4);
+ * // ...then impose it on stiff, quantized events.
+ * const quantized = [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 80 }];
+ * applyGrooveTemplate(quantized, template, ts); // events nudged toward the captured feel
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function applyGrooveTemplate(events: NoteEvent[], template: GrooveTemplate, ts: TimeSignature): NoteEvent[];
+
+/**
+ * Broad production style a progression preset suits.
+ *
+ * @category Composition
+ */
+type ProgStyle = 'minimal' | 'dance' | 'idol' | 'rock';
+/**
+ * Harmonic-function role of a progression as a whole.
+ *
+ * @category Composition
+ */
+type ProgFunction = 'loop' | 'tensionBuild' | 'cadenceStrong' | 'stable';
+/**
+ * A named chord-progression preset expressed in scale degrees.
+ *
+ * @category Composition
+ */
+type ProgressionPreset = {
+    id: string;
+    name: string;
+    degrees: number[];
+    functional: ProgFunction;
+    styles: ProgStyle[];
+};
+/**
+ * Options controlling {@link generateProgression}.
+ *
+ * @category Composition
+ */
+type ProgressionOptions = {
+    key: KeyScale;
+    style: ProgStyle;
+    bars: number;
+    presetId?: string;
+    ext?: ChordQuality | 'auto';
+    reharmonize?: boolean;
+    /**
+     * Seed for the deterministic preset choice and reharmonization.
+     *
+     * @defaultValue 0
+     */
+    seed?: number;
+};
+/**
+ * All built-in progression presets.
+ *
+ * @category Composition
+ */
+declare function progressions(): ProgressionPreset[];
+/**
+ * Presets whose style list includes the given style.
+ *
+ * @category Composition
+ */
+declare function progressionsByStyle(style: ProgStyle): 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
+ * 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
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { generateProgression, majorKey } from '@libraz/libcantus';
+ * const chords = generateProgression({ key: majorKey(0), style: 'dance', bars: 4 });
+ * // Deterministic for a given seed (defaults to 0); one ChordSpan per bar.
+ * ```
+ *
+ * @category Composition
+ */
+declare function generateProgression(opts: ProgressionOptions): ChordSpan[];
+
+/**
+ * A melody note supplied to the harmonizer: a {@link NoteEvent}.
+ *
+ * @category Reharmonization
+ */
+type MelodyNote = NoteEvent;
+/**
+ * Options controlling {@link harmonizeMelody}.
+ *
+ * @category Reharmonization
+ */
+type HarmonizeOptions = {
+    melody: MelodyNote[];
+    key: KeyScale | 'infer';
+    harmonicRhythm: number;
+    reharmonize: 'diatonic' | 'secondaryDominant' | 'borrowed';
+    placement: {
+        transposeSearch: boolean;
+        octaveSearch: boolean;
+    };
+    /**
+     * Seed for the deterministic tie-break perturbation.
+     *
+     * @defaultValue 0
+     */
+    seed?: number;
+};
+/**
+ * The chosen transpose, key, chord path, and per-note roles.
+ *
+ * @category Reharmonization
+ */
+type HarmonizeResult = {
+    transposeSemitones: number;
+    key: KeyScale;
+    chords: ChordSpan[];
+    melodyRoles: {
+        noteIndex: number;
+        role: HarmonyRole;
+    }[];
+};
+/**
+ * Harmonize a melody with a min-cost chord progression.
+ *
+ * The melody is segmented by `harmonicRhythm`; each segment is scored against
+ * diatonic (and, per `reharmonize`, secondary-dominant and borrowed) candidate
+ * chords by melody fit, and a Viterbi search picks the lowest-cost path using a
+ * functional-flow transition cost. When `placement.transposeSearch`/`octaveSearch`
+ * is set, the whole melody is transposed across a range and the best
+ * `(transpose, progression)` pair is returned; a small tessitura cost breaks
+ * 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}),
+ * 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.
+ * @returns The chosen transpose, key, chord path, and per-note roles.
+ * @example
+ * ```ts
+ * import { harmonizeMelody, majorKey } 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
+ * ```
+ * @category Reharmonization
+ */
+declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
+
+/**
+ * A transformation applicable to a motif cell.
+ *
+ * @category Composition
+ */
+type MotifTransform = 'transposeDiatonic' | 'transposeChromatic' | 'invert' | 'retrograde' | 'augment' | 'diminish' | 'sequence';
+/**
+ * A single note within a motif cell.
+ *
+ * @category Composition
+ */
+type MotifNote = {
+    pitch: number;
+    startBeat: number;
+    durationBeat: number;
+};
+/**
+ * A short melodic cell.
+ *
+ * @category Composition
+ */
+type MotifCell = {
+    notes: MotifNote[];
+};
+/**
+ * Melodic contour shape for {@link generateMotif}.
+ *
+ * @category Composition
+ */
+type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
+/**
+ * Options controlling {@link generateMotif}.
+ *
+ * @category Composition
+ */
+type MotifOptions = {
+    key: KeyScale;
+    chord?: Chord | null;
+    bars: number;
+    /**
+     * Melodic contour shape the line follows.
+     *
+     * @defaultValue `'arch'`
+     */
+    contour?: MotifContour;
+    /**
+     * Probability in [0, 1] that a note is nudged by a single diatonic step. The
+     * nudge direction is balanced (up or down with equal odds), so it adds
+     * variety without biasing the line off its contour. Default 0, which
+     * reproduces the requested contour exactly (no drift, tails return to tonic).
+     *
+     * @defaultValue 0
+     */
+    jitter?: number;
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
+    seed?: number;
+};
+/**
+ * Generate a short seed motif over `bars`.
+ *
+ * The melody follows the requested contour in diatonic steps from the tonic,
+ * snapped to the key. When a chord is supplied, notes landing on bar downbeats
+ * are pulled to the nearest chord tone. An optional `jitter` adds balanced
+ * per-note variation without biasing the contour; it is off by default, so the
+ * contour is reproduced exactly. Output is deterministic for a given seed.
+ *
+ * @param opts Key, optional chord, length, contour, jitter, and seed.
+ * @returns The generated motif cell.
+ *
+ * @example
+ * ```ts
+ * import { generateMotif, majorKey } from '@libraz/libcantus';
+ * const cell = generateMotif({ key: majorKey(0), bars: 2, contour: 'arch' });
+ * // cell.notes is a deterministic MotifCell (seed defaults to 0)
+ * ```
+ *
+ * @category Composition
+ */
+declare function generateMotif(opts: MotifOptions): MotifCell;
+/**
+ * Apply a transformation to a motif cell.
+ *
+ * `invert` reflects pitches about the first note (chromatic, self-inverse);
+ * `retrograde` mirrors onsets about the cell span, preserving rests (self-inverse);
+ * `augment`/`diminish` scale time by `amount ?? 2` and its reciprocal;
+ * `transposeChromatic` adds `amount` semitones; `transposeDiatonic` shifts by
+ * `amount` scale degrees when a `key` is given, or — with no `key` — falls back
+ * to a chromatic shift of `amount` semitones; `sequence` appends a shifted copy
+ * (by `amount` diatonic degrees with a `key`, or by `amount` semitones without
+ * one, since it delegates to `transposeDiatonic`).
+ *
+ * @param cell The cell to transform.
+ * @param t The transformation.
+ * @param amount Optional parameter (semitones, degrees, or time factor).
+ * @param key Key context for the diatonic transforms; without it,
+ *   `transposeDiatonic` and `sequence` shift chromatically by semitones.
+ * @returns The transformed cell.
+ *
+ * @example
+ * ```ts
+ * import { generateMotif, transformMotif, majorKey } from '@libraz/libcantus';
+ * const cell = generateMotif({ key: majorKey(0), bars: 1 });
+ * const inverted = transformMotif(cell, 'invert');
+ * ```
+ *
+ * @category Composition
+ */
+declare function transformMotif(cell: MotifCell, t: MotifTransform, amount?: number, key?: KeyScale): MotifCell;
+/**
+ * Lay a motif across `bars` and snap it to a chord timeline.
+ *
+ * The cell is tiled back-to-back to fill the requested span; each note is then
+ * pulled to the nearest chord tone of the segment sounding at its onset, so the
+ * developed line spells the underlying harmony.
+ *
+ * @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.
+ * @returns The developed, harmony-aware cell.
+ *
+ * @example
+ * ```ts
+ * import { chordTimelineFromChords, developMotif, generateMotif, majorKey } from '@libraz/libcantus';
+ * const key = majorKey(0);
+ * const timeline = chordTimelineFromChords([{ rootPc: 0, quality: 'maj', startBeat: 0 }], 8);
+ * const developed = developMotif(generateMotif({ key, bars: 1 }), timeline, key, 2);
+ * ```
+ *
+ * @category Composition
+ */
+declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: KeyScale, bars: number): MotifCell;
+
+/**
+ * Reharmonization: chord substitution, modal-interchange palettes, and negative
+ * harmony. These transforms take an existing chord (or a key) and propose
+ * alternative harmonies that preserve a chosen relationship — a shared function,
+ * a common tone, a tonicizing dominant, or a reflection across the key axis.
+ *
+ * Roots are pitch classes (0..11); no spelled key signature is required.
+ */
+
+/**
+ * The kind of substitution relationship a candidate realizes.
+ *
+ * @category Reharmonization
+ */
+type SubstitutionType = 'tritone' | 'relative' | 'borrowed' | 'chromatic-mediant' | 'secondary-dominant';
+/**
+ * A proposed chord substitution with its relationship, numeral, and function.
+ *
+ * @category Reharmonization
+ */
+type Substitution = {
+    chord: Chord;
+    type: SubstitutionType;
+    roman: string;
+    function: HarmonicFunction;
+};
+/**
+ * Options controlling which substitutions {@link substituteChord} returns.
+ *
+ * @category Reharmonization
+ */
+type SubstituteOptions = {
+    /**
+     * Melody pitch classes that must remain chord tones. When given, only
+     * substitutions whose pitch classes contain every listed pitch class are
+     * kept, so the melody stays consonant against the new harmony.
+     */
+    melodyPcs?: number[];
+};
+/**
+ * Propose substitutions for a chord within a key.
+ *
+ * Candidates are generated by several relationships and deduplicated against the
+ * 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
+ *   tone.
+ *
+ * Each result carries its Roman numeral and harmonic function in `key`. When
+ * `opts.melodyPcs` is given, only substitutions whose pitch classes contain all
+ * of those pitch classes are returned.
+ *
+ * @param chord The chord to reharmonize.
+ * @param key The prevailing key.
+ * @param opts Optional melody-preservation constraint.
+ * @returns The deduplicated substitution candidates.
+ * @example
+ * ```ts
+ * import { substituteChord, makeChord, majorKey } from '@libraz/libcantus';
+ * const subs = substituteChord(makeChord(7, 'dom7'), majorKey(0));
+ * // includes the tritone sub Db7 (rootPc 1, quality 'dom7')
+ * ```
+ * @category Reharmonization
+ */
+declare function substituteChord(chord: Chord, key: KeyScale, opts?: SubstituteOptions): Substitution[];
+/**
+ * A borrowed chord in the modal-interchange palette of a key.
+ *
+ * @category Reharmonization
+ */
+type BorrowedChord = {
+    chord: Chord;
+    roman: string;
+    source: BorrowedSource;
+};
+/**
+ * The modal-interchange palette of a key.
+ *
+ * Lists the diatonic triads of the {@link parallelKey} that are not diatonic to
+ * `key` (the classic borrowed chords such as `iv`, `bVI`, and `bVII` in a major
+ * key), plus the Neapolitan (a major triad on the flat second degree). Each
+ * carries its Roman numeral and {@link borrowedSource} relative to `key`.
+ *
+ * @param key The prevailing key.
+ * @returns The borrowed-chord palette.
+ * @category Reharmonization
+ */
+declare function modalInterchangePalette(key: KeyScale): BorrowedChord[];
+/**
+ * Reflect a chord across the tonic–dominant axis of a key (negative harmony).
+ *
+ * Every pitch class `p` maps to `(2*T + 7 - p) mod 12`, where `T` is the key
+ * tonic — the reflection that swaps the tonic with the dominant. The mirrored
+ * pitch classes (including the bass, if set) are reassembled into a chord by
+ * {@link detectChordBest}; when no chord is recognized, the mirrored root and
+ * the original quality are used as a fallback.
+ *
+ * @param chord The chord to reflect.
+ * @param key The prevailing key.
+ * @returns The negative-harmony counterpart of the chord.
+ * @example
+ * ```ts
+ * import { negativeHarmonyMirror, makeChord, majorKey } from '@libraz/libcantus';
+ * negativeHarmonyMirror(makeChord(7, 'maj'), majorKey(0));
+ * // G major reflected across C's axis => F minor (rootPc 5, quality 'min')
+ * ```
+ * @category Reharmonization
+ */
+declare function negativeHarmonyMirror(chord: Chord, key: KeyScale): Chord;
+
+/**
+ * Deterministic rhythm generation over a metric grid.
+ *
+ * Builds a fixed-resolution grid across one or more bars of a time signature
+ * and decides, per grid slot, whether it becomes a note onset. Onset
+ * probability follows the metric-accent hierarchy from the `meter` module, so
+ * strong positions (downbeats, secondary pulses) are favored over weak
+ * off-pulse subdivisions. Given a seed the output is fully reproducible.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the
+ * library-wide convention.
+ */
+
+/**
+ * A single rhythmic note: an onset position and how long it sounds.
+ *
+ * @category Rhythm & Meter
+ */
+type RhythmEvent = {
+    /** Onset position in quarter-note beats, absolute from the start of the span. */
+    position: number;
+    /** Duration in quarter-note beats, extending to the next onset. */
+    duration: number;
+};
+/**
+ * Options controlling {@link generateRhythm}.
+ *
+ * @category Rhythm & Meter
+ */
+type RhythmOptions = {
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
+    seed?: number;
+    /**
+     * Number of bars to generate.
+     *
+     * @defaultValue 1
+     */
+    bars?: number;
+    /**
+     * Grid resolution as the number of equal grid steps per quarter-note beat.
+     * The default of 2 yields an eighth-note grid; 4 yields a sixteenth-note
+     * grid, 3 an eighth-note triplet grid, and so on.
+     *
+     * @defaultValue 2
+     */
+    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.
+     *
+     * @defaultValue 0.5
+     */
+    density?: number;
+};
+/**
+ * Map a metric weight (0–3 from {@link metricWeight}) to a base onset
+ * probability before density scaling. Strong positions are much more likely to
+ * carry an onset than weak ones; the curve is intentionally small and explicit
+ * so its behavior is easy to inspect and test.
+ *
+ * @param weight The metric weight, 0 (off-pulse) to 3 (downbeat).
+ * @returns A base onset probability in [0, 1].
+ * @category Rhythm & Meter
+ */
+declare function onsetWeightCurve(weight: number): number;
+/**
+ * Generate a deterministic rhythmic pattern over `bars` bars of a time
+ * signature. A grid is built at the chosen subdivision; each slot becomes an
+ * onset with a probability derived from its metric weight scaled by `density`
+ * 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].
+ *
+ * @param ts The time signature.
+ * @param opts Generation options.
+ * @returns Onset events sorted by position, non-overlapping, covering the span.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, generateRhythm } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * generateRhythm(ts, { seed: 42, density: 0.6 }); // onset events over one bar
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): RhythmEvent[];
+/**
+ * Onset density of a generated pattern: the mean number of onsets per bar.
+ *
+ * @param events Events from {@link generateRhythm}.
+ * @param ts The time signature.
+ * @returns The onset count divided by the number of bars the events span.
+ * @category Rhythm & Meter
+ */
+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 };