@libraz/libsonare 1.7.2 → 1.8.1

package/src/realtime_engine.ts

@@ -1,13 +1,35 @@
-import { panLawCode, panModeCode, sendTimingCode, trackMonitorModeCode } from './codes';
+import {
+  panLawCode,
+  panModeCode,
+  sendTimingCode,
+  sidechainSourceKindCode,
+  trackMonitorModeCode,
+} from './codes';
 import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
-import type { ProjectMidiCcBinding, SynthPatch } from './project';
-import type { EqBand, PanLawInput, PanMode, SendTiming } from './public_types';
+import type {
+  Articulation,
+  ControllerBinding,
+  MpeDimension,
+  NoteTracking,
+  ProjectMidiCcBinding,
+  SynthPatch,
+} from './project';
+import { normalizeSynthInstrument } from './project_internal';
+import type {
+  EqBand,
+  PanLawInput,
+  PanMode,
+  SendTiming,
+  SidechainSourceKind,
+  UmpWords,
+} from './public_types';
 import type {
   WasmClipPageRequest,
   WasmEngineAutomationPoint,
   WasmEngineBounceOptions,
   WasmEngineBounceResult,
+  WasmEngineBus,
   WasmEngineCaptureStatus,
   WasmEngineClip,
   WasmEngineFreezeOptions,
@@ -23,6 +45,7 @@ import type {
   WasmEngineTelemetry,
   WasmEngineTempoSegment,
   WasmEngineTimeSignatureSegment,
+  WasmEngineTrackSend,
   WasmEngineTransportState,
   WasmExternalMidiEvent,
   WasmRealtimeEngine,
@@ -94,15 +117,37 @@ export interface EngineBus {
    * to stereo.
    */
   channelLayout?: number;
+  /**
+   * Bus this bus's output sums into instead of the master mix (bus-to-bus
+   * routing); 0 or absent keeps it on the master mix.
+   */
+  outputBusId?: number;
+  /**
+   * Sends to other buses, in the same shape as a track lane's sends. A
+   * pre-fader send taps before `gainDb`, a post-fader one after it.
+   */
+  sends?: EngineTrackSend[];
 }
 
 export interface EngineMidiEvent {
-  renderFrame: number;
+  /** Absolute render frame for this event. Default `0`. */
+  renderFrame?: number;
   word0?: number;
   word1?: number;
   word2?: number;
   word3?: number;
   wordCount?: number;
+  /**
+   * Redundant with `word0`, which already carries the UMP group in bits 24..27.
+   * The engine reads the group from `word0` — the form that reaches a device or
+   * a file — so packing it there is sufficient and a value here that contradicts
+   * `word0` is ignored. Must still be in `[0, 15]`; anything else is rejected as
+   * a malformed event. Default `0`.
+   *
+   * Utility (`word0` type nibble `0x0`) and UMP Stream (`0xF`) messages have no
+   * group field — those bits are Reserved and `form`/`status` respectively — so
+   * they always read as group `0` and packing a group into them has no effect.
+   */
   group?: number;
   sysexHandle?: number;
   data0?: number;
@@ -119,6 +164,20 @@ export interface EngineMidiClipSchedule {
   loop?: boolean;
   loopLengthSamples?: number;
   events: EngineMidiEvent[];
+  /**
+   * Linear gain applied to the destination instrument's rendered audio while
+   * this clip is the most recently started active clip on it. Absent defaults
+   * to `1` (unity).
+   */
+  gain?: number;
+  /**
+   * Linear fade lengths over the clip's full length (not per internal loop
+   * repeat). Absent defaults to `0` (no fade). `fadeOutSamples` above `0` is
+   * rejected when `lengthSamples` is absent or `<= 0` (open-ended): an
+   * open-ended clip has no end to fade out towards.
+   */
+  fadeInSamples?: number;
+  fadeOutSamples?: number;
 }
 
 export const EXPECTED_ENGINE_ABI_VERSION = 3;
@@ -131,6 +190,76 @@ export interface MidiCcBindOptions {
   maxValue?: number;
 }
 
+/** Request form of {@link RealtimeEngine.renderOffline}. */
+export interface RenderOfflineRequest {
+  /** One buffer per output plane; their common length is the render span. */
+  channels: Float32Array[];
+  /** Render block size. Default `128`. */
+  blockSize?: number;
+  /**
+   * Whether this call ends the timeline. `true` (the default, and what a
+   * one-shot bounce wants) releases every sounding note and flushes the PDC /
+   * alignment delay lines before returning. `false` renders one CHUNK of a
+   * longer timeline: a note held across the chunk boundary keeps sounding into
+   * the next call and the delay lines carry their history over, so consecutive
+   * chunks concatenate to exactly what one continuous render of the same span
+   * produces. Call {@link RealtimeEngine.finishOfflineRender} once after the
+   * last chunk.
+   *
+   * Sample-exact concatenation requires every chunk to use the same `blockSize`
+   * and a frame count that is a whole number of blocks: each call restarts the
+   * block grid at its own frame 0 and renders a short final block for the
+   * remainder, and the clip / automation / MIDI-clip snapshots are frozen once
+   * per block, so a chunk that ends mid-block shifts every later block
+   * boundary. Audio stays continuous either way; only bit-identity is lost.
+   */
+  finalize?: boolean;
+}
+
+const UMP_WORD_MIN = -0x80000000;
+const UMP_WORD_MAX = 0xffffffff;
+
+// A word may be spelled `(0x4 << 28) | …`, which is a signed int once bit 31 is
+// set, so the signed 32-bit range is accepted alongside the unsigned one.
+function assertUmpWords(fnName: string, words: UmpWords): UmpWords {
+  if (!(words instanceof Uint32Array) && !Array.isArray(words)) {
+    throw new TypeError(`${fnName}: words must be a Uint32Array or a number array`);
+  }
+  if (words.length < 1 || words.length > 4) {
+    throw new RangeError(`${fnName}: words must hold 1 to 4 words`);
+  }
+  for (let i = 0; i < words.length; i++) {
+    const word = words[i];
+    if (
+      typeof word !== 'number' ||
+      !Number.isInteger(word) ||
+      word < UMP_WORD_MIN ||
+      word > UMP_WORD_MAX
+    ) {
+      throw new RangeError(`${fnName}: words[${i}] must be an integer 32-bit word`);
+    }
+  }
+  return words;
+}
+
+/**
+ * One normalizer for both call forms, so the request object and the positional
+ * overload cannot drift in their defaults.
+ */
+function normalizeRenderOfflineRequest(
+  channelsOrRequest: Float32Array[] | RenderOfflineRequest,
+  blockSize: number,
+): { channels: Float32Array[]; blockSize: number; finalize: boolean } {
+  const request = Array.isArray(channelsOrRequest)
+    ? { channels: channelsOrRequest, blockSize }
+    : channelsOrRequest;
+  return {
+    channels: request.channels,
+    blockSize: request.blockSize ?? 128,
+    finalize: request.finalize ?? true,
+  };
+}
+
 export interface EngineCapabilities {
   engineAbiVersion: number;
   expectedEngineAbiVersion: number;
@@ -162,6 +291,7 @@ export function engineCapabilities(): EngineCapabilities {
 
 export class RealtimeEngine {
   private native: WasmRealtimeEngine;
+  private released = false;
 
   constructor(
     sampleRate = 48000,
@@ -186,6 +316,15 @@ export class RealtimeEngine {
     );
   }
 
+  /**
+   * Size the engine's queues and scratch for a sample rate and block size.
+   *
+   * `commandCapacity` must not exceed 65536 and `telemetryCapacity` must not
+   * exceed 16384; a larger value throws and leaves the engine untouched. The
+   * telemetry number is not a queue depth paid for one-for-one: the engine
+   * reserves that many meter records per metered lane, so its memory cost is
+   * far larger than the number given here.
+   */
   prepare(
     sampleRate: number,
     maxBlockSize: number,
@@ -249,12 +388,16 @@ export class RealtimeEngine {
    * scheduled MIDI clips routed to that destination render through the synth.
    * Unknown preset names throw. An object patch's `destinationId` is a JS
    * binding convenience, not part of the NativeSynth patch itself.
+   *
+   * An `engineMode: 'sample'` patch also carries the {@link SampleBank} its
+   * keymap names. The synth takes a share of the bank, so it may be released
+   * right after this call; a sample patch bound without one renders silence.
    */
   setSynthInstrument(
     patch: SynthPatch | string = {},
     destinationId = (typeof patch === 'object' ? patch.destinationId : undefined) ?? 0,
   ): void {
-    this.native.setSynthInstrument(destinationId, patch);
+    this.native.setSynthInstrument(destinationId, normalizeSynthInstrument(patch));
   }
 
   /**
@@ -282,6 +425,8 @@ export class RealtimeEngine {
       gain?: number;
       polyphony?: number;
       preferModelForModeledFamilies?: boolean;
+      clearBankRig?: boolean;
+      gsEfxRealization?: 'modern' | 'classic';
     } = {},
     destinationId = config.destinationId ?? 0,
   ): void {
@@ -329,6 +474,135 @@ export class RealtimeEngine {
     return this.native.midiCcBindingCount();
   }
 
+  /**
+   * Replace a destination instrument's controller profile with a named preset
+   * (see {@link controllerProfileNames}). Installing a profile drops every
+   * channel's accumulated axis values: the new bindings say nothing about what
+   * the old ones had reached. An unknown name throws, and so does a destination
+   * with no instrument or one whose instrument holds no profile.
+   */
+  setControllerProfile(destinationId: number, presetName: string): void {
+    this.native.setControllerProfile(destinationId, presetName);
+  }
+
+  /** Add one {@link ControllerBinding} on top of the destination's current profile. */
+  bindController(destinationId: number, binding: ControllerBinding): void {
+    this.native.bindController(destinationId, binding);
+  }
+
+  /**
+   * Drop every binding of the destination's controller profile. The instrument
+   * keeps a profile; it resolves nothing until something is bound again.
+   */
+  clearControllerBindings(destinationId: number): void {
+    this.native.clearControllerBindings(destinationId);
+  }
+
+  controllerBindingCount(destinationId: number): number {
+    return this.native.controllerBindingCount(destinationId);
+  }
+
+  /**
+   * Whether note-on velocity is expression for this instrument. No fixed
+   * default is possible — a wind controller ships sending breath-derived
+   * velocity on one model and a constant on the next — so each preset states it
+   * and a host building its own profile sets it. When false the synth takes
+   * every note at full scale and the bound axes carry the dynamics alone.
+   */
+  setControllerVelocityMeaningful(destinationId: number, meaningful: boolean): void {
+    this.native.setControllerVelocityMeaningful(destinationId, meaningful);
+  }
+
+  controllerVelocityMeaningful(destinationId: number): boolean {
+    return this.native.controllerVelocityMeaningful(destinationId);
+  }
+
+  /**
+   * Say which note a value addressed to a whole MIDI channel belongs to when
+   * several are sounding on it, for one per-note dimension
+   * ({@link MPE_DIMENSIONS}, {@link NOTE_TRACKINGS}).
+   *
+   * Set per dimension because the useful answers differ: pressure following the
+   * newest note while bend reaches every one is a real configuration, not a
+   * mistake. MPE poses this question and declines to answer it, so this is a
+   * choice rather than a rule — and it is read only inside an MPE zone, and
+   * only while more than one note is sounding on the channel, which an MPE
+   * sender avoids by giving each note its own member channel.
+   *
+   * Both arguments are required and are a name or its ordinal; an unknown
+   * spelling is refused rather than resolved to a default, as are a destination
+   * with no instrument and one whose instrument holds no controller profile.
+   */
+  setControllerNoteTracking(
+    destinationId: number,
+    dimension: MpeDimension | number,
+    tracking: NoteTracking | number,
+  ): void {
+    this.native.setControllerNoteTracking(destinationId, dimension, tracking);
+  }
+
+  /**
+   * Read back {@link setControllerNoteTracking} for one dimension, as the
+   * canonical name.
+   */
+  controllerNoteTracking(
+    destinationId: number,
+    dimension: MpeDimension | number,
+  ): NoteTracking | number {
+    return this.native.controllerNoteTracking(destinationId, dimension);
+  }
+
+  /**
+   * Set how one MIDI channel (0–15) of a destination's instrument treats a
+   * note-on while another note on that channel is still held: `'poly'` takes a
+   * new voice each time, `'mono-retrigger'` stops and restarts the note (what
+   * GS MONO MODE and CC126 mean), `'mono-legato'` carries the sounding voice
+   * and only moves its pitch — a wind player's slur, which no MIDI message can
+   * reach by design.
+   *
+   * `'mono-legato'` is a request, not a guarantee: an engine whose exciter is
+   * spent at the onset — anything struck or plucked — and a target pitch below
+   * what the engine's delay line can hold both fall back to an ordinary note,
+   * which {@link legatoFallbackCount} counts. A channel outside [0,15] and an
+   * articulation outside the enum are refused rather than clamped, and so is a
+   * destination with no instrument or one whose instrument has no articulation
+   * of its own.
+   */
+  setArticulation(
+    destinationId: number,
+    channel: number,
+    articulation: Articulation | number,
+  ): void {
+    this.native.setArticulation(destinationId, channel, articulation);
+  }
+
+  /**
+   * Read back {@link setArticulation} as the canonical name. An ordinal this
+   * build cannot spell is handed back as the number, the way every other enum
+   * leaves this surface.
+   */
+  articulation(destinationId: number, channel: number): Articulation | number {
+    return this.native.articulation(destinationId, channel);
+  }
+
+  /**
+   * How many times a legato continuation was asked for on this destination and
+   * refused, so the note started a voice of its own instead. Counted rather
+   * than inferred: a refusal sounds like an ordinary note, so nothing in the
+   * audio separates "this engine declines legato" from "the mode was never
+   * set". Saturates at 4294967295 rather than wrapping — matching the C ABI, so
+   * the same phrase reports the same number on every surface — after which it
+   * reads as "at least this many".
+   *
+   * Throws on a destination with no instrument, and on one whose instrument has
+   * no articulation of its own — the same two refusals
+   * {@link setArticulation} keeps apart. Reporting 0 for the second would read
+   * as "every slur took", which is the reading this counter exists to prevent.
+   */
+  legatoFallbackCount(destinationId: number): number {
+    return this.native.legatoFallbackCount(destinationId);
+  }
+
   /** Install/replace a live non-destructive MIDI-FX insert for one destination. */
   setMidiFx(destinationId: number, configJson: string): void {
     this.native.setMidiFx(destinationId, configJson);
@@ -354,7 +628,10 @@ export class RealtimeEngine {
   /**
    * Route a destination's (track lane's) MIDI to the external output queue
    * instead of the internal instrument rack, so the track plays an external
-   * device. Clearing it restores internal-synth playback.
+   * device. Clearing it restores internal-synth playback. Control-thread only.
+   * The change takes effect at the next processed block; switching a
+   * destination's route first releases its notes and resets its controllers
+   * through the old route, and drops its pending MIDI-FX events. Single writer.
    */
   setMidiDestinationExternal(destinationId: number, external: boolean): void {
     this.native.setMidiDestinationExternal(destinationId, external);
@@ -383,6 +660,12 @@ export class RealtimeEngine {
    * block / animation frame. `maxRecords` caps the number of output events
    * returned — the shared unit across every surface. Events past the cap stay
    * queued for the next call (lossless); call again to drain the rest.
+   *
+   * One queued record lowers to at most 4 MIDI 1.0 messages (a MIDI 2.0
+   * registered or assignable controller becomes CC 101/100 or 99/98 plus Data
+   * Entry 6/38), so a positive `maxRecords` below 4 could never consume a record
+   * and is rejected with an `InvalidParameter` `SonareError` instead of
+   * returning nothing forever.
    */
   drainExternalMidi(maxRecords = 1024): WasmExternalMidiEvent[] {
     return this.native.drainExternalMidi(maxRecords);
@@ -398,7 +681,11 @@ export class RealtimeEngine {
   }
 
   externalMidiScratchRenderFrame(): number {
-    return this.native.externalMidiScratchRenderFrame();
+    // embind marshals the int64 render frame as a BigInt; the declared `number`
+    // has to be a real number or the first consumer that does arithmetic on it
+    // dies with "Cannot mix BigInt". Same normalization as the telemetry, meter
+    // and scope scratch frames.
+    return Number(this.native.externalMidiScratchRenderFrame());
   }
 
   externalMidiScratchByteWord(): number {
@@ -443,6 +730,50 @@ export class RealtimeEngine {
     this.native.pushMidiInputCc(group, channel, controller, value, portTimeSamples);
   }
 
+  /**
+   * Push a live MIDI pitch bend to the engine-owned MIDI input source.
+   *
+   * `bend14` is unsigned 14-bit with centre 8192 (0..16383) — the dimension is
+   * not 7-bit, so a value past 16383 is refused rather than narrowed. The input
+   * source must be enabled with {@link setMidiInputSource} first.
+   */
+  pushMidiInputPitchBend(
+    group: number,
+    channel: number,
+    bend14: number,
+    portTimeSamples = 0,
+  ): void {
+    this.native.pushMidiInputPitchBend(group, channel, bend14, portTimeSamples);
+  }
+
+  /**
+   * Push a live MIDI channel pressure to the engine-owned MIDI input source.
+   * `pressure` is 7-bit (0..127). Under MPE this is the member channel's
+   * per-note pressure.
+   */
+  pushMidiInputChannelPressure(
+    group: number,
+    channel: number,
+    pressure: number,
+    portTimeSamples = 0,
+  ): void {
+    this.native.pushMidiInputChannelPressure(group, channel, pressure, portTimeSamples);
+  }
+
+  /**
+   * Push a live MIDI polyphonic key pressure to the engine-owned MIDI input
+   * source. `note` and `pressure` are 7-bit (0..127).
+   */
+  pushMidiInputPolyPressure(
+    group: number,
+    channel: number,
+    note: number,
+    pressure: number,
+    portTimeSamples = 0,
+  ): void {
+    this.native.pushMidiInputPolyPressure(group, channel, note, pressure, portTimeSamples);
+  }
+
   pushMidiNoteOn(
     destinationId: number,
     group: number,
@@ -482,16 +813,86 @@ export class RealtimeEngine {
     this.native.pushMidiCc(destinationId, group, channel, controller, value, renderFrame);
   }
 
-  /** Queue one immediate MIDI 1.0 channel-voice UMP word for a destination. */
-  pushMidiUmp(destinationId: number, word0: number, renderFrame = -1): void {
-    this.native.pushMidiUmp(destinationId, word0, renderFrame);
+  /**
+   * Queue an immediate (live) MIDI pitch bend to a MIDI destination. `bend14`
+   * is unsigned 14-bit with centre 8192 (0..16383); `renderFrame` is the frame
+   * to fire at, or -1 for immediate. Mirrors the Node/Python/C-ABI
+   * `pushMidiPitchBend`.
+   */
+  pushMidiPitchBend(
+    destinationId: number,
+    group: number,
+    channel: number,
+    bend14: number,
+    renderFrame = -1,
+  ): void {
+    this.native.pushMidiPitchBend(destinationId, group, channel, bend14, renderFrame);
+  }
+
+  /**
+   * Queue an immediate (live) MIDI channel pressure to a MIDI destination.
+   * `pressure` is 7-bit (0..127); `renderFrame` is the frame to fire at, or -1
+   * for immediate. Mirrors the Node/Python/C-ABI `pushMidiChannelPressure`.
+   */
+  pushMidiChannelPressure(
+    destinationId: number,
+    group: number,
+    channel: number,
+    pressure: number,
+    renderFrame = -1,
+  ): void {
+    this.native.pushMidiChannelPressure(destinationId, group, channel, pressure, renderFrame);
+  }
+
+  /**
+   * Queue an immediate (live) MIDI polyphonic key pressure to a MIDI
+   * destination. `note` and `pressure` are 7-bit (0..127); `renderFrame` is the
+   * frame to fire at, or -1 for immediate. Mirrors the Node/Python/C-ABI
+   * `pushMidiPolyPressure`.
+   */
+  pushMidiPolyPressure(
+    destinationId: number,
+    group: number,
+    channel: number,
+    note: number,
+    pressure: number,
+    renderFrame = -1,
+  ): void {
+    this.native.pushMidiPolyPressure(destinationId, group, channel, note, pressure, renderFrame);
+  }
+
+  /**
+   * Queue an immediate (live) raw UMP message to a MIDI destination. `words` is
+   * 1 to 4 words, most significant first, and its length must match the message
+   * type of `words[0]`. MIDI 2.0 channel-voice messages (MT 0x4) arrive at full
+   * width; SysEx7 / data messages (MT 0x3 / 0x5) are refused, use
+   * {@link pushMidiSysex}. Throws when the slot ring or command queue is full
+   * (retry after a process block). `renderFrame` is the render-frame time to
+   * apply, or -1 for immediate. A bare number is accepted as a one-word
+   * message.
+   */
+  pushMidiUmp(destinationId: number, words: UmpWords | number, renderFrame = -1): void {
+    const list = typeof words === 'number' ? [words] : words;
+    this.native.pushMidiUmp(destinationId, assertUmpWords('pushMidiUmp', list), renderFrame);
+  }
+
+  /**
+   * Push one raw UMP message (1 to 4 words) to the engine-owned MIDI input
+   * source. The message rules match {@link pushMidiUmp}. `portTimeSamples` is
+   * the port timestamp in samples.
+   */
+  pushMidiInputUmp(words: UmpWords, portTimeSamples = 0): void {
+    this.native.pushMidiInputUmp(assertUmpWords('pushMidiInputUmp', words), portTimeSamples);
   }
 
   /**
    * Queue an immediate (live) MIDI SysEx frame to a MIDI destination. `data` is
    * the full message including the leading 0xF0 and trailing 0xF7 (1..512
-   * bytes). `renderFrame` is the frame to fire at, or -1 for immediate. Mirrors
-   * the Node/Python/C-ABI `pushMidiSysex`.
+   * bytes). `renderFrame` is the frame to fire at, or -1 for immediate. Throws
+   * `InvalidParameter` when the destination instrument cannot prepare
+   * the SysEx (retrying cannot help), and `OutOfMemory` when the payload
+   * slots or the command queue are full (retry after a processed block).
+   * Mirrors the Node/Python/C-ABI `pushMidiSysex`.
    */
   pushMidiSysex(destinationId: number, data: Uint8Array, renderFrame = -1): void {
     this.native.pushMidiSysex(destinationId, data, renderFrame);
@@ -518,14 +919,34 @@ export class RealtimeEngine {
     return this.native.getTransportState();
   }
 
+  /** Queues an integrated-loudness reset; short-term and momentary windows are retained. */
+  resetMasterLoudnessMeter(renderFrame = -1): void {
+    this.native.resetMasterLoudnessMeter(renderFrame);
+  }
+
+  /** Reads the immutable factory value for a resolved insert parameter id. */
+  insertParameterConstructedValue(paramId: number): number {
+    return this.native.insertParameterConstructedValue(paramId);
+  }
+
   play(renderFrame = -1): void {
     this.native.play(renderFrame);
   }
 
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   stop(renderFrame = -1): void {
     this.native.stop(renderFrame);
   }
 
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   seekSample(timelineSample: number, renderFrame = -1): void {
     this.native.seekSample(timelineSample, renderFrame);
   }
@@ -540,11 +961,26 @@ export class RealtimeEngine {
     this.native.settleParameters();
   }
 
+  /** Snap only insert automation slots after structural replay. */
+  settleInsertParameters(): void {
+    this.native.settleInsertParameters();
+  }
+
   /** Drains queued commands on an offline/control-only engine immediately. */
   flushControlCommands(): void {
     this.native.flushControlCommands();
   }
 
+  /** Applies commands already due on a control-only mirror, retaining future commands. */
+  applyCommandsDueNowPreservingFuture(): void {
+    this.native.applyCommandsDueNowPreservingFuture();
+  }
+
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   seekPpq(ppq: number, renderFrame = -1): void {
     this.native.seekPpq(ppq, renderFrame);
   }
@@ -570,6 +1006,11 @@ export class RealtimeEngine {
     return Number(this.native.sampleAtPpq(ppq));
   }
 
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   setLoop(startPpq: number, endPpq: number, enabled = true): void {
     this.native.setLoop(startPpq, endPpq, enabled);
   }
@@ -582,11 +1023,11 @@ export class RealtimeEngine {
     return this.native.parameterCount();
   }
 
-  parameterInfoByIndex(index: number): EngineParameterInfo {
+  parameterInfoByIndex(index: number): Required<EngineParameterInfo> {
     return this.native.parameterInfoByIndex(index);
   }
 
-  parameterInfo(id: number): EngineParameterInfo {
+  parameterInfo(id: number): Required<EngineParameterInfo> {
     return this.native.parameterInfo(id);
   }
 
@@ -671,24 +1112,28 @@ export class RealtimeEngine {
     return this.native.clipCount();
   }
 
+  /**
+   * Normalizes each send's pre/post tap point to the integer the native layer
+   * reads (defaults to post-fader when omitted). Shared by track lanes and
+   * buses, which carry the same send shape.
+   */
+  private static normalizeSends(sends: EngineTrackSend[]): WasmEngineTrackSend[] {
+    return sends.map((send) => ({
+      ...send,
+      // Post-fader (0) is the default for an omitted sendTiming.
+      sendTiming: send.sendTiming === undefined ? 0 : sendTimingCode(send.sendTiming),
+    }));
+  }
+
   setTrackLanes(lanes: Array<number | EngineTrackLane>): void {
     this.native.setTrackLanes(
       lanes.map((lane) => {
         if (typeof lane === 'number') {
           return { trackId: lane };
         }
-        if (!lane.sends) {
-          return lane;
-        }
-        // Normalize each send's pre/post tap point to the integer the native
-        // layer reads (defaults to post-fader when omitted).
         return {
           ...lane,
-          sends: lane.sends.map((send) => ({
-            ...send,
-            // Post-fader (0) is the default for an omitted sendTiming.
-            sendTiming: send.sendTiming === undefined ? 0 : sendTimingCode(send.sendTiming),
-          })),
+          sends: lane.sends ? RealtimeEngine.normalizeSends(lane.sends) : undefined,
         };
       }),
     );
@@ -703,7 +1148,43 @@ export class RealtimeEngine {
   }
 
   setTrackBuses(buses: EngineBus[]): void {
-    this.native.setTrackBuses(buses);
+    // Array.isArray guards a caller-fabricated array-like (e.g. `{ length }`)
+    // meant to probe the native array-length read: passing it through
+    // unmodified lets that guard see the real (missing) length rather than
+    // failing here on a `.map` that array-likes do not implement.
+    this.native.setTrackBuses(
+      Array.isArray(buses)
+        ? buses.map((bus) => ({
+            ...bus,
+            sends: bus.sends ? RealtimeEngine.normalizeSends(bus.sends) : undefined,
+          }))
+        : (buses as WasmEngineBus[]),
+    );
+  }
+
+  /**
+   * Keys one insert of a bus strip from a track lane or another bus
+   * (ducking/sidechainRouter inserts). `sourceId` 0 removes the binding.
+   */
+  setBusSidechain(
+    busId: number,
+    insertIndex: number,
+    sourceKind: SidechainSourceKind | number,
+    sourceId: number,
+  ): void {
+    this.native.setBusSidechain(busId, insertIndex, sidechainSourceKindCode(sourceKind), sourceId);
+  }
+
+  /**
+   * Keys one insert of the master strip from a track lane or a bus. Same
+   * source rules as {@link setBusSidechain}.
+   */
+  setMasterSidechain(
+    insertIndex: number,
+    sourceKind: SidechainSourceKind | number,
+    sourceId: number,
+  ): void {
+    this.native.setMasterSidechain(insertIndex, sidechainSourceKindCode(sourceKind), sourceId);
   }
 
   setBusStripJson(busId: number, sceneJson: string): void {
@@ -747,6 +1228,19 @@ export class RealtimeEngine {
     this.native.setTrackStripInsertBypassed(trackId, insertIndex, bypassed, resetOnBypass);
   }
 
+  /** Bus-strip counterpart of {@link setTrackStripEqBand}. */
+  setBusStripEqBand(busId: number, bandIndex: number, band: EqBand | string): void {
+    this.native.setBusStripEqBandJson(
+      busId,
+      bandIndex,
+      typeof band === 'string' ? band : JSON.stringify(band),
+    );
+  }
+
+  setBusStripEqBandJson(busId: number, bandIndex: number, bandJson: string): void {
+    this.native.setBusStripEqBandJson(busId, bandIndex, bandJson);
+  }
+
   setMasterStripJson(sceneJson: string): void {
     try {
       JSON.parse(sceneJson);
@@ -778,10 +1272,12 @@ export class RealtimeEngine {
 
   /**
    * Changes one track-strip insert parameter in realtime, addressed by the
-   * processor's JSON-key parameter name (see {@link masteringInsertParamInfo}).
-   * Applied at the next block head via the engine command queue; safe during
-   * playback. Throws if the track, insert, or name is unknown, the param is not
-   * realtime-safe, or the command queue is full.
+   * processor's JSON-key parameter name — one of the entries
+   * {@link masteringInsertParamInfo} reports with a non-null `id`; a
+   * construction-only entry (`id` null) takes effect only when the insert is
+   * built. Applied at the next block head via the engine command queue; safe
+   * during playback. Throws if the track, insert, or name is unknown, the
+   * param is not realtime-safe, or the command queue is full.
    */
   setTrackStripInsertParamByName(
     trackId: number,
@@ -792,11 +1288,43 @@ export class RealtimeEngine {
     this.native.setTrackStripInsertParamByName(trackId, insertIndex, paramName, value);
   }
 
+  /** Apply a live insert edit on this engine's owning thread without draining its command queue. */
+  applyTrackStripInsertParamByNameNow(
+    trackId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ): boolean {
+    return this.native.applyTrackStripInsertParamByNameNow(trackId, insertIndex, paramName, value);
+  }
+
+  /** Restore a retained insert value exactly after a strip scene is replayed. */
+  restoreTrackStripInsertParamByName(
+    trackId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ): void {
+    this.native.restoreTrackStripInsertParamByName(trackId, insertIndex, paramName, value);
+  }
+
   /** Master-strip counterpart of {@link setTrackStripInsertParamByName}. */
   setMasterStripInsertParamByName(insertIndex: number, paramName: string, value: number): void {
     this.native.setMasterStripInsertParamByName(insertIndex, paramName, value);
   }
 
+  applyMasterStripInsertParamByNameNow(
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ): boolean {
+    return this.native.applyMasterStripInsertParamByNameNow(insertIndex, paramName, value);
+  }
+
+  restoreMasterStripInsertParamByName(insertIndex: number, paramName: string, value: number): void {
+    this.native.restoreMasterStripInsertParamByName(insertIndex, paramName, value);
+  }
+
   /** Bus-strip counterpart of {@link setTrackStripInsertParamByName}. */
   setBusStripInsertParamByName(
     busId: number,
@@ -807,6 +1335,42 @@ export class RealtimeEngine {
     this.native.setBusStripInsertParamByName(busId, insertIndex, paramName, value);
   }
 
+  applyBusStripInsertParamByNameNow(
+    busId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ): boolean {
+    return this.native.applyBusStripInsertParamByNameNow(busId, insertIndex, paramName, value);
+  }
+
+  restoreBusStripInsertParamByName(
+    busId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ): void {
+    this.native.restoreBusStripInsertParamByName(busId, insertIndex, paramName, value);
+  }
+
+  /**
+   * Forgets the remembered manual insert-parameter values of one track strip
+   * and discards its queued insert edits. Call before {@link setTrackStripJson}
+   * replaces the strip when its old values must not carry over; the setter
+   * never does this itself, since a queued edit may already target the new chain.
+   */
+  clearTrackInsertParameterBases(trackId: number): void {
+    this.native.clearTrackInsertParameterBases(trackId);
+  }
+
+  clearBusInsertParameterBases(busId: number): void {
+    this.native.clearBusInsertParameterBases(busId);
+  }
+
+  clearMasterInsertParameterBases(): void {
+    this.native.clearMasterInsertParameterBases();
+  }
+
   /** Bus-strip counterpart of {@link setTrackStripInsertBypassed}. */
   setBusStripInsertBypassed(
     busId: number,
@@ -832,6 +1396,16 @@ export class RealtimeEngine {
    * stages of the offline mastering chain (`repair.*`, `loudness`, and the
    * match stages) have no insert form and no automation id: they buffer the
    * entire signal by construction and do not run on the realtime path.
+   *
+   * The returned id uses the track's current positional lane selector. When
+   * `setTrackLanes` successfully changes lane order or membership, the engine
+   * remaps already queued and published track automation by track id, but it
+   * cannot update a numeric id retained by the caller. Re-resolve every track
+   * insert id after such a topology change before passing it to
+   * `setAutomationLane`, `setParameter`, or `setParameterSmoothed`. Use
+   * `setTrackStripInsertParamByName` when the operation needs a stable track
+   * identity. Master and bus insert ids are separate and are not invalidated by
+   * track-lane changes.
    */
   resolveTrackInsertAutomationId(trackId: number, insertIndex: number, paramName: string): number {
     return this.native.resolveTrackInsertAutomationId(trackId, insertIndex, paramName);
@@ -845,6 +1419,42 @@ export class RealtimeEngine {
     return this.native.resolveBusInsertAutomationId(busId, insertIndex, paramName);
   }
 
+  /**
+   * Resolves a hosted instrument's continuous parameter (by its JSON-key name)
+   * to the reserved automation id usable with `setAutomationLane` /
+   * `setParameter`, so an instrument parameter is driven at audio-block
+   * precision exactly like a strip insert. Returns `-1` when the destination
+   * has no bound instrument, the instrument exposes no automatable parameters,
+   * or the name is unknown.
+   *
+   * For the NativeSynth ({@link setSynthInstrument}) the names are the
+   * continuous {@link SynthPatch} fields: `gain`, `busDrive`, `cutoffHz`,
+   * `resonanceQ`, `drive`, `keyTrack`, `envToCutoffCents`, `velToCutoffCents`,
+   * `ampAttackMs`, `ampDecayMs`, `ampSustain`, `ampReleaseMs`,
+   * `filterAttackMs`, `filterDecayMs`, `filterSustain`, `filterReleaseMs`,
+   * `lfoRateHz`, `lfoToPitchCents`, `lfo2RateHz`, `glideMs`, `bodyMix`,
+   * `stereoSpread`, `detuneCents`, `driftCents`, `pitchOffsetCents`,
+   * `hpCutoffHz`, `sampleHoldHz`, `bitDepth`.
+   *
+   * Structural fields (`preset`, `engineMode`, `waveform`, `filterModel`,
+   * `unison`, `polyphony`, `body`, `modRoutings`) are not automatable and
+   * return `-1`: they resize voice pools or swap DSP topology, which is not
+   * audio-thread safe. Rebind the instrument with a new patch instead.
+   *
+   * `gain`, `busDrive`, `cutoffHz`, `resonanceQ`, `envToCutoffCents`,
+   * `lfoToPitchCents` and `pitchOffsetCents` reach voices that are already
+   * sounding from the next block; the rest are cached into per-voice state at
+   * note-on and take effect from the next note, so a lane that moves one of
+   * them under a held note looks inert until the next one speaks — that is the
+   * behaviour, not a dropped write.
+   *
+   * The id survives an unbind/rebind of the same destination and applies
+   * nothing while that destination is unbound.
+   */
+  resolveInstrumentAutomationId(destinationId: number, paramName: string): number {
+    return this.native.resolveInstrumentAutomationId(destinationId, paramName);
+  }
+
   /** Sets a track lane strip's pan position in realtime (glitch-free). */
   setTrackStripPan(trackId: number, pan: number): void {
     this.native.setTrackStripPan(trackId, pan);
@@ -865,6 +1475,29 @@ export class RealtimeEngine {
     this.native.setTrackStripDualPan(trackId, leftPan, rightPan);
   }
 
+  /**
+   * Sets a bus strip's output pan position in realtime (glitch-free). Throws
+   * for an unknown bus or one wider than stereo.
+   */
+  setBusStripPan(busId: number, pan: number): void {
+    this.native.setBusStripPan(busId, pan);
+  }
+
+  /** Sets a bus strip's pan law in realtime. */
+  setBusStripPanLaw(busId: number, panLaw: PanLawInput): void {
+    this.native.setBusStripPanLaw(busId, panLawCode(panLaw));
+  }
+
+  /** Sets a bus strip's pan mode in realtime. */
+  setBusStripPanMode(busId: number, panMode: PanMode | number): void {
+    this.native.setBusStripPanMode(busId, panModeCode(panMode));
+  }
+
+  /** Sets a bus strip's dual-pan left/right positions in realtime. */
+  setBusStripDualPan(busId: number, leftPan: number, rightPan: number): void {
+    this.native.setBusStripDualPan(busId, leftPan, rightPan);
+  }
+
   /**
    * Sets a track lane strip's inter-channel alignment delay (whole samples).
    * Adjusts strip latency, so PDC and reported graph latency are refreshed.
@@ -919,6 +1552,57 @@ export class RealtimeEngine {
     return this.native.clipPageRequestOverflowCount();
   }
 
+  /** Cumulative warp-stretch requests dropped because the native queue was full. */
+  warpStretchOverflowCount(): number {
+    return this.native.warpStretchOverflowCount();
+  }
+
+  /**
+   * Sets the number of concurrent time-stretch voices. `voices` must be an
+   * integer in `[0, 64]`; a non-integer, negative, or larger value throws and
+   * leaves the capacity unchanged. Default is 8. Capacity 0 disables
+   * time-stretch, so every warped clip plays resampled instead and none of
+   * that counts toward {@link warpStretchOverflowCount}. A change applied
+   * while the engine is running restarts the splice state of any clip
+   * stretching through a voice at that moment. Control-thread only.
+   */
+  setWarpVoiceCapacity(voices: number): void {
+    this.native.setWarpVoiceCapacity(voices);
+  }
+
+  /** Reads the current time-stretch voice capacity (default 8). */
+  warpVoiceCapacity(): number {
+    return this.native.warpVoiceCapacity();
+  }
+
+  /**
+   * Sets the clip-page look-ahead window in timeline frames.
+   *
+   * The player reports the pages it is *about to* read that are not resident
+   * yet, so a streaming host can service them before the audio thread reaches
+   * them. Without look-ahead a page miss is only reported after the read
+   * already produced silence, which costs one block of silence at every page
+   * boundary the host has not primed — the reason a sliding-window streamer
+   * cannot keep a live playhead fed from miss reports alone.
+   *
+   * Look-ahead requests drain through the same `popClipPageRequest` queue and
+   * are queued *after* the block's genuine misses, so a host that keeps only
+   * the newest request per clip (as {@link ClipPageStreamer} does) tracks the
+   * look-ahead frontier.
+   *
+   * `prepare` defaults this to half a second at the engine's sample rate. `0`
+   * disables the look-ahead. A clip whose pages are all resident produces no
+   * requests at all, with or without look-ahead. Safe to call during playback.
+   */
+  setClipPagePrefetchFrames(frames: number): void {
+    this.native.setClipPagePrefetchFrames(frames);
+  }
+
+  /** Current clip-page look-ahead window in timeline frames. */
+  clipPagePrefetchFrames(): number {
+    return this.native.clipPagePrefetchFrames();
+  }
+
   setCaptureBuffer(numChannels: number, capacityFrames: number): void {
     this.native.setCaptureBuffer(numChannels, capacityFrames);
   }
@@ -1027,14 +1711,52 @@ export class RealtimeEngine {
     return this.native.processWithMonitor(channels);
   }
 
-  renderOffline(channels: Float32Array[], blockSize = 128): Float32Array[] {
-    return this.native.renderOffline(channels, blockSize);
+  /**
+   * Render `channels` offline from the current transport position. Requesting
+   * more planes than `prepare` reserved throws an `InvalidParameter`
+   * `SonareError` rather than returning silence that reads as a finished render.
+   *
+   * Set `finalize: false` to render one chunk of a longer timeline; see
+   * {@link RenderOfflineRequest.finalize} and {@link finishOfflineRender}.
+   */
+  renderOffline(request: RenderOfflineRequest): Float32Array[];
+  renderOffline(channels: Float32Array[], blockSize?: number): Float32Array[];
+  renderOffline(
+    channelsOrRequest: Float32Array[] | RenderOfflineRequest,
+    blockSize = 128,
+  ): Float32Array[] {
+    const request = normalizeRenderOfflineRequest(channelsOrRequest, blockSize);
+    return this.native.renderOffline(request.channels, request.blockSize, request.finalize);
+  }
+
+  /**
+   * End a chunked offline render: release every note the sequencer still holds
+   * and flush the PDC / alignment delay lines. Required after
+   * `renderOffline({ finalize: false })`; the finalizing form does it itself.
+   *
+   * Skipping it leaves every note still sounding at the last chunk held. On an
+   * engine-internal instrument the tail simply never releases; on a destination
+   * marked external ({@link RealtimeEngine.setMidiDestinationExternal}) the
+   * note-ons already left through the external MIDI queue, so the note-offs
+   * emitted here are the only ones the receiving device will get and the notes
+   * otherwise hang outside the engine.
+   */
+  finishOfflineRender(): void {
+    this.native.finishOfflineRender();
   }
 
+  /**
+   * Bounce the timeline to an interleaved buffer. `numChannels` above the
+   * prepared channel count throws an `InvalidParameter` `SonareError`.
+   */
   bounceOffline(options: EngineBounceOptions): EngineBounceResult {
     return this.native.bounceOffline(options);
   }
 
+  /**
+   * Freeze the current graph to audio. `numChannels` above the prepared channel
+   * count throws an `InvalidParameter` `SonareError`.
+   */
   freezeOffline(options: EngineFreezeOptions): EngineFreezeResult {
     return this.native.freezeOffline(options);
   }
@@ -1084,6 +1806,12 @@ export class RealtimeEngine {
   meterScratchRenderFrame(): number {
     return Number(this.native.meterScratchRenderFrame());
   }
+  meterScratchInputPeakDbL(): number {
+    return this.native.meterScratchInputPeakDbL();
+  }
+  meterScratchInputPeakDbR(): number {
+    return this.native.meterScratchInputPeakDbR();
+  }
   meterScratchValue(field: number): number {
     return this.native.meterScratchValue(field);
   }
@@ -1095,9 +1823,10 @@ export class RealtimeEngine {
   /**
    * Drains pending meter telemetry as per-plane (wide) records for a surround
    * target. Use this for a surround mix target; {@link drainMeterTelemetry}
-   * stays the stereo fast path. The two share one queue — call only one per
-   * target. The live AudioWorklet path owns the queue via the stereo drain, so
-   * this wide drain is for an offline (non-worklet) engine instance; per-plane
+   * stays the stereo fast path. The two share one queue and each consumes every
+   * target's records, so an engine uses only one of them. The live AudioWorklet
+   * path owns the queue via the stereo drain, so this wide drain is for an
+   * offline (non-worklet) engine instance; per-plane
    * surround meters are not delivered over the live worklet meter ring.
    */
   drainMeterTelemetryWide(maxRecords = 1024): EngineMeterTelemetryWide[] {
@@ -1144,9 +1873,19 @@ export class RealtimeEngine {
     return this.native.scopeScratchPointRight(index);
   }
 
+  /** Release the underlying WASM object. Idempotent, as the Node facade is. */
   destroy(): void {
+    if (this.released) {
+      return;
+    }
+    this.released = true;
     this.native.delete();
   }
+
+  /** Alias for {@link destroy}, matching embind's own release method name. */
+  delete(): void {
+    this.destroy();
+  }
 }
 
 export class ClipPageProvider {