@libraz/libsonare 1.7.1 → 1.8.0

package/dist/instrument_types.d.ts

@@ -0,0 +1,517 @@
+/**
+ * Instrument definitions a project source plays through: the built-in synth
+ * patch, the SoundFont player, and the sample bank's descriptors.
+ */
+import type { SampleBank } from './sample_bank';
+/** Names accepted by the minimal built-in oscillator synth. */
+export declare const BUILTIN_SYNTH_WAVEFORMS: readonly ["sine", "saw", "sawtooth", "square", "triangle"];
+/** Oscillator waveform for the built-in synth. */
+export type BuiltinSynthWaveform = (typeof BUILTIN_SYNTH_WAVEFORMS)[number] | 0 | 1 | 2 | 3;
+/**
+ * Built-in synth patch + MIDI routing for
+ * {@link Project.bounceWithBuiltinInstrument}. Every field is optional; a
+ * non-positive (or omitted) numeric field falls back to the C-ABI default
+ * (gain 0.2, attack 5ms, decay 60ms, sustain 0.7, release 120ms, 16 voices),
+ * so `{}` is a usable default sine patch.
+ */
+export interface BuiltinSynthBinding {
+    /** MIDI destination id this patch answers to (default 0; see {@link Project.setTrackMidiDestination}). */
+    destinationId?: number;
+    /**
+     * Oscillator waveform (default `'sine'`). The one field with no nearest
+     * sensible value — a name or an ordinal outside the set throws rather than
+     * falling back to sine.
+     */
+    waveform?: BuiltinSynthWaveform;
+    /** Master output gain, linear (0 => 0.2). */
+    gain?: number;
+    /** ADSR attack in ms (0 => 5). */
+    attackMs?: number;
+    /** ADSR decay in ms (0 => 60). */
+    decayMs?: number;
+    /** ADSR sustain level [0,1] (0 => 0.7). */
+    sustain?: number;
+    /** ADSR release in ms (0 => 120). */
+    releaseMs?: number;
+    /** Max simultaneous voices (0 => 16, clamped to [1, 64]). */
+    polyphony?: number;
+}
+/**
+ * Cross-binding alias of {@link BuiltinSynthBinding}. The same built-in-synth
+ * patch concept is named `BuiltinSynthConfig` in the Python binding; this alias
+ * lets portable code use that shared name on the WASM surface too.
+ */
+export type BuiltinSynthConfig = BuiltinSynthBinding;
+/**
+ * SoundFont (SF2) player patch + MIDI routing for
+ * {@link Project.bounceWithSf2Instrument}. Every field is optional; a
+ * non-positive (or omitted) numeric field falls back to the C-ABI default
+ * (gain 0.5, 48 voices), so `{}` is a usable default patch.
+ */
+export interface Sf2InstrumentConfig {
+    /** MIDI destination id this player answers to (default 0; see {@link Project.setTrackMidiDestination}). */
+    destinationId?: number;
+    /** Master output gain, linear (0 => 0.5). */
+    gain?: number;
+    /** Max simultaneous voices (0 => 48, clamped to [1, 64]). */
+    polyphony?: number;
+    /** Prefer dedicated physical models for covered melodic GM programs. Defaults to false; drums stay SF2-first. */
+    preferModelForModeledFamilies?: boolean;
+    /**
+     * Render the instrument alone, without the stage the bank binds after its
+     * voice — the amplifier and cabinet an electric guitar is never heard
+     * without. Defaults to false, so a MIDI file that selects a distorted guitar
+     * and asks for nothing else still comes out amplified. Set it to get the
+     * direct signal, which is what a voice is calibrated against.
+     */
+    clearBankRig?: boolean;
+    /**
+     * How the GS insertion effects (EFX) are realised: 'modern' (default) or
+     * 'classic'. Any other value is refused by name.
+     */
+    gsEfxRealization?: 'modern' | 'classic';
+}
+/** Source backend a resolved MIDI program renders through. */
+export type SourceBackend = 'sf2' | 'synth';
+/**
+ * One {@link Project.soundFontManifest} entry: a (channel, bank, program)
+ * combination the arrangement plays, with the backend it resolves to.
+ */
+export interface Sf2ProgramStatus {
+    /** MIDI channel (0-15). */
+    channel: number;
+    /** Effective SF2 bank (drum channels report 128). */
+    bank: number;
+    /** Program number (0-127). */
+    program: number;
+    /** `'sf2'` when the loaded SoundFont covers the program, else `'synth'`. */
+    backend: SourceBackend;
+    /** Resolved SF2 preset name (GS fallback included); empty for `'synth'`. */
+    presetName: string;
+}
+/**
+ * Every NativeSynth engine selector, by ordinal.
+ *
+ * @remarks
+ * Not seventeen interchangeable choices. Selecting a mode blanks every engine
+ * section but its own, and four engines have nothing to voice until a section
+ * is supplied: `'fm'` needs operators, `'modal'` a mode table, `'percussion'` a
+ * kit and `'sample'` a {@link SampleBank}. Each renders exact silence from an
+ * otherwise default patch (measured: peak 0), while the other thirteen sound
+ * and differ from one another. A host offering this array as a control offers
+ * those four as dead entries unless it also supplies the section, which a
+ * preset does.
+ */
+export declare const SYNTH_ENGINE_MODES: readonly ["default", "subtractive", "fm", "karplus-strong", "modal", "additive", "percussion", "piano", "pipe-organ", "bowed-string", "reed", "brass", "flute", "plucked-string", "vocal", "free-reed", "harpsichord", "sample"];
+export declare const SAMPLE_LOOP_MODES: readonly ["default", "none", "continuous", "key-down"];
+export declare const SAMPLE_KEY_TRACKS: readonly ["default", "on", "off"];
+export declare const SYNTH_RETRIGGERS: readonly ["default", "free", "note"];
+export declare const SYNTH_OSC_WAVEFORMS: readonly ["default", "sine", "saw", "square", "triangle", "noise"];
+export declare const SYNTH_FILTER_MODELS: readonly ["default", "svf", "moog-ladder", "diode-ladder", "sallen-key"];
+export declare const SYNTH_FILTER_OUTPUTS: readonly ["default", "lowpass", "bandpass", "highpass"];
+export declare const SYNTH_BODY_TYPES: readonly ["default", "none", "guitar", "violin", "wood-tube", "brass-bell", "vocal"];
+export declare const SYNTH_MOD_SOURCES: readonly ["none", "amp-env", "filter-env", "lfo1", "lfo2", "velocity", "key-track", "mod-wheel", "random", "breath", "aftertouch", "expression-cc", "pitch-bend"];
+export declare const SYNTH_MOD_DESTINATIONS: readonly ["none", "pitch-cents", "cutoff-cents", "amp-gain", "pan-units", "resonance-q", "vibrato-depth-cents", "filter-env-depth", "lfo1-rate-scale", "excitation-force", "excitation-position", "excitation-brightness", "spectrum-morph"];
+/** How a device spells a gesture (see {@link ControllerBinding}). */
+export declare const CONTROLLER_INPUTS: readonly ["control-change", "channel-pressure", "poly-pressure", "pitch-bend", "velocity"];
+/** What a gesture means — the expression axis a binding drives. */
+export declare const CONTROLLER_AXES: readonly ["none", "excitation", "position", "brightness", "morph", "loudness", "pitch-cents", "vibrato-depth"];
+/**
+ * What a channel does with a note-on while another note on that channel is
+ * still held. `'mono-legato'` carries the sounding voice and only moves its
+ * pitch — a wind player's slur — and is deliberately out of reach of any MIDI
+ * message: CC126 names a monophonic mode but not this one.
+ */
+export declare const ARTICULATIONS: readonly ["poly", "mono-retrigger", "mono-legato"];
+/** The three dimensions MPE carries per note ({@link RealtimeEngine.setControllerNoteTracking}). */
+export declare const MPE_DIMENSIONS: readonly ["bend", "pressure", "timbre"];
+/**
+ * Which note a value addressed to a whole MIDI channel belongs to when several
+ * are sounding on it ({@link RealtimeEngine.setControllerNoteTracking}).
+ *
+ * MPE poses this question and declines to answer it — how a controller affects
+ * the notes when more than one is active on a member channel is left to the
+ * device — so this is a choice rather than a rule. A released note is never
+ * selected, whatever the rule and however long a pedal keeps it sounding.
+ */
+export declare const NOTE_TRACKINGS: readonly ["last", "lowest", "highest", "all"];
+export interface SynthEnumTables {
+    engineModes: string[];
+    waveforms: string[];
+    builtinWaveforms: string[];
+    filterModels: string[];
+    filterOutputs: string[];
+    bodyTypes: string[];
+    modSources: string[];
+    modDestinations: string[];
+    controllerInputs: string[];
+    controllerAxes: string[];
+    articulations: string[];
+    mpeDimensions: string[];
+    noteTrackings: string[];
+}
+/** NativeSynth engine selector ({@link SynthPatch}; `'default'` keeps the base patch's). */
+export type SynthEngineMode = (typeof SYNTH_ENGINE_MODES)[number];
+/**
+ * Per-patch loop override for the sample engine (`'default'` keeps what the
+ * bank recorded for the sample the zone names).
+ *
+ * A different set of values from {@link SampleDesc.loopMode}, which is the
+ * SoundFont `sampleModes` number describing the recording itself.
+ */
+export type SampleLoopMode = (typeof SAMPLE_LOOP_MODES)[number];
+/** Whether a sample follows the played key (`'default'` keeps the base patch's). */
+export type SampleKeyTrack = (typeof SAMPLE_KEY_TRACKS)[number];
+/**
+ * What a note-on restarts on a {@link SynthPatch} (`'default'` keeps the base
+ * patch's). `'free'` seeds each voice's start phases and random streams from
+ * the voice slot and a running note count, so two plays of one note differ;
+ * `'note'` seeds them from the note number alone.
+ */
+export type SynthRetrigger = (typeof SYNTH_RETRIGGERS)[number];
+/**
+ * Loop behaviour recorded for one sample in a {@link SampleBank}.
+ *
+ * A number is the raw SoundFont `sampleModes` value the C struct carries
+ * (`0` no loop, `1` continuous, `3` while the key is held), so SF2-derived data
+ * passes through untranslated; the names are the readable spellings of the same
+ * three states. There is no `'default'`: a sample's own loop mode is where the
+ * default comes from.
+ */
+export type SampleDescLoopMode = 'none' | 'continuous' | 'key-down';
+/**
+ * Tuning and looping of one sample, in units relative to that sample
+ * ({@link SampleBank.addSample}).
+ *
+ * Every field is optional and the omitted state is meaningful: the empty
+ * descriptor is an unlooped sample rooted at middle C and played at the
+ * render's own rate.
+ */
+export interface SampleDesc {
+    /** MIDI key at which the sample sounds at its recorded pitch. Defaults to 60. */
+    rootKey?: number;
+    /** Fine tuning applied on top of {@link SampleDesc.rootKey}. */
+    fineTuneCents?: number;
+    /** Rate the sample was recorded at; omit to play it at the render's rate. */
+    sourceRate?: number;
+    /** Loop start, as a frame offset inside this sample. */
+    loopStart?: number;
+    /** Loop end, as a frame offset inside this sample. */
+    loopEnd?: number;
+    /**
+     * The sample's own loop behaviour. A loop that survives clamping empty is
+     * dropped, so a malformed loop plays unlooped rather than wrapping over
+     * nothing. {@link SynthPatch.sampleLoop} overrides this per patch.
+     */
+    loopMode?: SampleDescLoopMode | number;
+}
+/**
+ * One key/velocity rectangle mapped onto a sample ({@link SampleBank.addZone}).
+ *
+ * Every bound defaults on its own, so narrowing one edge never collapses
+ * another: an omitted upper bound is `127`, an omitted `velLo` is `1` (velocity
+ * zero is a note-off, not a dynamic), and an omitted `keyLo` is simply the
+ * lowest key. `{ keyLo: 48 }` is therefore keys 48-127 at every velocity and
+ * `{ velLo: 64 }` its exact mirror, while an empty rectangle is the whole
+ * keyboard. The one rectangle this cannot express is the single key `0`.
+ */
+export interface SampleZoneDesc {
+    /**
+     * Keymap set the zone joins; a {@link SynthPatch} names a set through
+     * {@link SynthPatch.sampleSet}. Sets below it are created. Defaults to `0`.
+     */
+    setIndex?: number;
+    /** Sample the zone plays, as returned by {@link SampleBank.addSample}. */
+    sampleIndex?: number;
+    /** Lowest key of the rectangle. Defaults to `0`. */
+    keyLo?: number;
+    /** Highest key of the rectangle. Defaults to `127`. */
+    keyHi?: number;
+    /** Lowest velocity of the rectangle. Defaults to `1`. */
+    velLo?: number;
+    /** Highest velocity of the rectangle. Defaults to `127`. */
+    velHi?: number;
+    /** Added to the sample's own fine tuning. */
+    tuneCents?: number;
+    /** Linear gain; omit for unity. */
+    gain?: number;
+    /** Pan in the voice mixer's units, `-500` to `500`. */
+    panUnits?: number;
+}
+/** NativeSynth oscillator waveform (`'default'` keeps the base patch's). */
+export type SynthOscWaveform = (typeof SYNTH_OSC_WAVEFORMS)[number];
+/** NativeSynth filter model — the character core (`'default'` keeps the base patch's). */
+export type SynthFilterModel = (typeof SYNTH_FILTER_MODELS)[number];
+/** NativeSynth filter output (SVF only; `'default'` keeps the base patch's). */
+export type SynthFilterOutput = (typeof SYNTH_FILTER_OUTPUTS)[number];
+/** NativeSynth body/formant resonance voicing (`'default'` keeps the base patch's). */
+export type SynthBodyType = (typeof SYNTH_BODY_TYPES)[number];
+/** {@link SynthPatch} mod-matrix source. */
+export type SynthModSource = (typeof SYNTH_MOD_SOURCES)[number];
+/** {@link SynthPatch} mod-matrix destination. */
+export type SynthModDestination = (typeof SYNTH_MOD_DESTINATIONS)[number];
+/** Input side of a {@link ControllerBinding}: how the device spells the gesture. */
+export type ControllerInput = (typeof CONTROLLER_INPUTS)[number];
+/** Output side of a {@link ControllerBinding}: which expression axis it means. */
+export type ControllerAxis = (typeof CONTROLLER_AXES)[number];
+/** Per-channel note-overlap rule ({@link RealtimeEngine.setArticulation}). */
+export type Articulation = (typeof ARTICULATIONS)[number];
+/** One per-note MPE dimension ({@link MPE_DIMENSIONS}). */
+export type MpeDimension = (typeof MPE_DIMENSIONS)[number];
+/** One note-attribution rule ({@link NOTE_TRACKINGS}). */
+export type NoteTracking = (typeof NOTE_TRACKINGS)[number];
+/**
+ * One device gesture bound to one expression axis
+ * ({@link RealtimeEngine.bindController}).
+ *
+ * Binding the same input twice with different axes is how a single gesture
+ * reaches two of them, which is what a breath controller driving both
+ * excitation and loudness needs. `input` and `axis` are required and are the
+ * canonical names (or their C ordinals); an unknown name throws rather than
+ * resolving to the first member.
+ *
+ * @example
+ * ```ts
+ * engine.bindController(0, { input: 'control-change', index: 2, axis: 'excitation' });
+ * ```
+ */
+export interface ControllerBinding {
+    /** How the device spells the gesture. */
+    input: ControllerInput | number;
+    /**
+     * CC number 0-127 for `'control-change'`. Every other input is identified by
+     * its message status alone and ignores this. Default `0`.
+     */
+    index?: number;
+    /**
+     * Which expression axis the gesture means. `'none'` is refused: a binding
+     * that means nothing is a caller mistake, not an empty slot.
+     */
+    axis: ControllerAxis | number;
+    /**
+     * Axis value at zero deflection, in the axis's own unit — normalized `[0,1]`
+     * for the excitation axes and loudness, cents for pitch and vibrato depth.
+     * Default `0`.
+     */
+    lo?: number;
+    /** Axis value at full deflection; `lo > hi` inverts the gesture. Default `1`. */
+    hi?: number;
+    /**
+     * Exponent applied to the normalized input before the range maps it. Default
+     * `1` (linear) and deliberately so: a wind controller has already applied the
+     * curve its player chose, and a second one on this side bends a gesture that
+     * was already shaped. Must be finite and positive.
+     */
+    curve?: number;
+}
+/** One {@link SynthPatch} mod-matrix routing (name or C ordinal per field). */
+export interface SynthModRouting {
+    /**
+     * Mod-matrix source. `'none'` is refused: a routing driven by nothing is a
+     * caller mistake, not an empty slot.
+     */
+    source: SynthModSource | number;
+    /**
+     * Mod-matrix destination. `'none'` is refused, for the same reason as
+     * `source`.
+     */
+    destination: SynthModDestination | number;
+    /**
+     * Destination units at full source deflection, summed onto whatever the
+     * patch or a CC already set and then handled per destination:
+     *
+     * - `pan-units`: SF2 pan units, clamped to `[-500, 500]` — `1` moves the
+     *   image by about 0.2% of a side.
+     * - `amp-gain` / `filter-env-depth`: multiplicative. Each routing's amount
+     *   composes onto a running multiplier that clamps to `[0, 4]`.
+     *   `filter-env-depth` has nothing to scale while the patch's
+     *   `envToCutoffCents` is `0` — the filter envelope contributes no cents for
+     *   it to multiply.
+     * - `resonance-q`: added to the patch's own Q, then floored at a fixed
+     *   `0.5` (not at that patch's own Q).
+     * - `lfo1-rate-scale`: multiplicative, clamped to `[1/16, 16]`. Audible only
+     *   once something else already reads LFO1's output — vibrato depth, the
+     *   filter's LFO amount, tremolo — since it retunes LFO1 rather than
+     *   sounding on its own; the bare patch's built-in mod-wheel vibrato is the
+     *   usual path.
+     * - The three `excitation-*` destinations and `spectrum-morph`: an offset in
+     *   the engine's own normalized `[0, 1]` axis units, the same scale the
+     *   live-control CCs drive, clamped to `[-1, 1]`. Reach is per engine and not
+     *   uniform across the three: `excitation-force` reaches pipe organ, bowed
+     *   string, reed, brass, flute and free reed; `excitation-position` reaches
+     *   bowed string only; `excitation-brightness` reaches pipe organ, reed,
+     *   brass, flute, free reed and vocal. An engine outside a destination's list
+     *   ignores it — its exciter is finished before the second sample renders, or
+     *   it has none. `spectrum-morph` travels between the two spectral tables an
+     *   additive patch carries; a patch needs an explicit `drawbars_b` distinct
+     *   from `drawbars` to have a second table to travel to, and no catalog
+     *   preset ships one, so the destination is currently unreachable from a
+     *   preset name alone.
+     *
+     * Percussion reaches none of the above: a drum channel's voice runs the
+     * per-note kit patch instead of this one, so the whole mod matrix is
+     * discarded before the voice starts.
+     */
+    depth: number;
+}
+/**
+ * Versioned NativeSynth patch for {@link Project.bounceWithSynthInstrument}
+ * and {@link RealtimeEngine.setSynthInstrument}.
+ *
+ * The patch starts from a BASE — the named `preset` (see
+ * {@link synthPresetNames}; a `"va:"` routing prefix is accepted) or, when
+ * `preset` is omitted, the default subtractive patch. Omitting a numeric field
+ * keeps the base value; supplying one overrides it (clamped to its audible
+ * range), including an explicit `0` such as `stereoSpread: 0`. The enum fields
+ * reserve `'default'` as keep. A `modRoutings` array REPLACES the base mod
+ * matrix, and an empty array clears it, while omitting the key keeps it.
+ *
+ * Mode-specific deep parameters (FM operator stacks, modal mode tables,
+ * drawbar registrations, kit pieces, piano strings) travel inside the named
+ * presets; the patch exposes the wrapper sections most engines share. Two
+ * exceptions: `waveform` is read by the subtractive engine only, and on a
+ * percussion channel the whole section below is discarded in favor of the
+ * per-note drum-kit patch — only `gain`, `busDrive` and `polyphony` still act.
+ */
+export interface SynthPatch {
+    /**
+     * Optional binding convenience for JS realtime/offline helpers. It is not
+     * part of the NativeSynth patch itself; Python uses explicit
+     * `(destination_id, patch)` bindings instead. Defaults to `0`.
+     */
+    destinationId?: number;
+    /** Resolve MIDI channels from incoming GM bank/program changes; defaults to false. */
+    useGmPrograms?: boolean;
+    /** Base preset name (see {@link synthPresetNames}); omit for the init patch. */
+    preset?: string;
+    engineMode?: SynthEngineMode | number;
+    /** Oscillator waveform. Read by the subtractive engine only; every other engine ignores it. */
+    waveform?: SynthOscWaveform | number;
+    /** Detuned-stack width [1, 7]. */
+    unison?: number;
+    detuneCents?: number;
+    /** Per-voice slow pitch drift depth (cents). */
+    driftCents?: number;
+    /** Pre-filter drive [0, 1]. */
+    drive?: number;
+    filterModel?: SynthFilterModel | number;
+    filterOutput?: SynthFilterOutput | number;
+    cutoffHz?: number;
+    /**
+     * Series 12 dB/oct highpass after the main filter, in Hz; 0 disables the
+     * stage. The other end of a band the lowpass alone cannot make. It runs at
+     * Butterworth Q -- `resonanceQ` belongs to the main filter.
+     */
+    hpCutoffHz?: number;
+    /**
+     * Rate the voice's output is held at, in Hz; 0 disables the stage. The
+     * voice's own converter, ahead of its amplitude envelope: the aliased images
+     * it folds down are as much of a sound as its samples are. Per voice, so a
+     * patch layering several voices can convert some and leave others alone.
+     *
+     * Percussion never reads this: a drum channel's voice runs the per-note kit
+     * patch instead of this one, so the field is discarded before the voice
+     * starts.
+     */
+    sampleHoldHz?: number;
+    /**
+     * Word length the held value is quantized to, in bits; 0 disables the
+     * quantizer. Fractional values are meaningful — a converter's effective
+     * resolution is rarely a whole number of bits.
+     */
+    bitDepth?: number;
+    resonanceQ?: number;
+    /** Cutoff keyboard tracking [0, 1]. */
+    keyTrack?: number;
+    /**
+     * Filter envelope's cutoff depth, in cents at full envelope; 0 leaves the
+     * envelope's cutoff contribution off. The cutoff is multiplied by
+     * 2^(envelope × envToCutoffCents / 1200), so the response moves by exactly
+     * that interval wherever the corner sits well below Nyquist; near the top the
+     * `svf` moves slightly less and the ladders slightly more. `cutoffHz` is the
+     * −3 dB corner only for `svf` at `resonanceQ` 0.707: with resonance the `svf`
+     * corner sits above it, and the ladder and Sallen-Key models put their
+     * resonant peak on it with the −3 dB point one to three octaves lower, so
+     * measure a depth as a ratio of corners rather than against `cutoffHz`.
+     */
+    envToCutoffCents?: number;
+    /**
+     * Velocity's cutoff depth, in cents. The rendered term is
+     * `velToCutoffCents * (velocity / 127 - 1)`, so velocity 127 is the anchor
+     * where it is exactly zero: a positive value darkens softer notes, a
+     * negative value brightens them, and both effects grow the further the
+     * velocity sits below 127.
+     */
+    velToCutoffCents?: number;
+    /**
+     * Constant transposition of the voice's own pitch, in cents, clamped to
+     * [-4800, 4800]; 0 leaves the pitch alone. Applied on top of the note, so it
+     * shifts a whole patch without rewriting the part — a detuned layer, a sample
+     * set mapped a semitone off, an instrument pitched to a reference other than
+     * A440. Carried in the per-sample pitch factor every engine's render already
+     * takes, so it applies the same amount on all of them — except percussion,
+     * whose per-note kit patch replaces this whole section and never reads it.
+     *
+     * Also automatable under this same name through
+     * {@link RealtimeEngine.resolveInstrumentAutomationId}; it is one of the names
+     * that reaches a voice that is already sounding, rather than waiting for the
+     * next note.
+     */
+    pitchOffsetCents?: number;
+    ampAttackMs?: number;
+    ampDecayMs?: number;
+    ampSustain?: number;
+    ampReleaseMs?: number;
+    filterAttackMs?: number;
+    filterDecayMs?: number;
+    filterSustain?: number;
+    filterReleaseMs?: number;
+    lfoRateHz?: number;
+    lfoToPitchCents?: number;
+    lfo2RateHz?: number;
+    glideMs?: number;
+    body?: SynthBodyType | number;
+    /** Body resonance mix [0, 1]. */
+    bodyMix?: number;
+    /** Seeded per-voice pan scatter [0, 1]. */
+    stereoSpread?: number;
+    /**
+     * Seed source for each voice's start state. `'note'` derives oscillator start
+     * phases, unison jitter, drift and every engine's noise stream from the note
+     * number, so the same note played again after its tail has ended renders the
+     * same samples; `'free'` (the built-in patches' choice) varies them per note.
+     * State outside the voice is reset by neither: controllers, the bus DC
+     * blocker, a piano's shared soundboard, a plucked string's sympathetic halo,
+     * an organ's wind chest and effect tails. The `'drum-kit'` preset's per-note
+     * pieces keep their own mode.
+     */
+    retrigger?: SynthRetrigger | number;
+    /** Mod matrix (at most 8 routings; REPLACES the base matrix when non-empty). */
+    modRoutings?: SynthModRouting[];
+    /** Master output gain (linear). */
+    gain?: number;
+    /** Max simultaneous voices [1, 64]. */
+    polyphony?: number;
+    /** Gain-neutral bus saturation [0, 1]. */
+    busDrive?: number;
+    /**
+     * Bank the sample engine reads its PCM from. Binding convenience for the JS
+     * offline helpers rather than part of the patch itself, like `destinationId`:
+     * it is resolved to a native handle before the patch crosses into WASM.
+     * A `'sample'` patch bound without a bank renders silence.
+     */
+    sampleBank?: SampleBank;
+    /**
+     * Keymap set in the bound bank (negative selects none). Read only by a
+     * `'sample'` patch, which is what lets set `0` stay addressable without a
+     * "keep the base value" sentinel of its own.
+     */
+    sampleSet?: number;
+    /** Linear gain on the sample. */
+    sampleLevel?: number;
+    sampleLoop?: SampleLoopMode | number;
+    /** Attack skip, as a fraction of the mapped region. */
+    sampleStartOffset?: number;
+    sampleKeyTrack?: SampleKeyTrack | number;
+}
+//# sourceMappingURL=instrument_types.d.ts.map

package/dist/instrument_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument_types.d.ts","sourceRoot":"","sources":["../src/instrument_types.ts"],"names":[],"mappings":"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"}

package/dist/live_audio.d.ts

@@ -0,0 +1,35 @@
+import type { SonareRealtimeEngineNode } from './worklet';
+export interface BindMicrophoneInputOptions extends MediaStreamConstraints {
+    /**
+     * Stream to bind instead of requesting one. Supplying it also transfers
+     * ownership: {@link MicrophoneInputBinding.close} leaves its tracks running,
+     * because they may be feeding a recorder, a level meter or a second
+     * `AudioContext` that this binding knows nothing about.
+     */
+    stream?: MediaStream;
+    /**
+     * Whether {@link MicrophoneInputBinding.close} stops the stream's audio
+     * tracks. Defaults to whether this binding acquired the stream itself: `true`
+     * for a stream it requested through `getUserMedia`, `false` for one the
+     * caller supplied. Set it explicitly to override in either direction.
+     */
+    stopTracksOnClose?: boolean;
+}
+export interface MicrophoneInputBinding {
+    stream: MediaStream;
+    source: MediaStreamAudioSourceNode;
+    /** Whether this binding acquired {@link stream} rather than being handed one. */
+    ownsStream: boolean;
+    close(): void;
+}
+/**
+ * Route microphone audio into a realtime engine node.
+ *
+ * Ownership is decided by provenance, the same rule `ownsWorker` applies in
+ * `opfs_clip_pages.ts` and `worker_client.ts`: a resource the caller handed in
+ * is the caller's to release. `close()` used to stop the tracks of a supplied
+ * stream by default, which killed a microphone the rest of the page was still
+ * using.
+ */
+export declare function bindMicrophoneInput(context: AudioContext, engine: SonareRealtimeEngineNode | AudioWorkletNode, options?: BindMicrophoneInputOptions): Promise<MicrophoneInputBinding>;
+//# sourceMappingURL=live_audio.d.ts.map

package/dist/live_audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live_audio.d.ts","sourceRoot":"","sources":["../src/live_audio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB;IACxE;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,0BAA0B,CAAC;IACnC,iFAAiF;IACjF,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,wBAAwB,GAAG,gBAAgB,EACnD,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,sBAAsB,CAAC,CAgCjC"}