@libraz/libsonare 1.7.1 → 1.8.0

package/src/project_class.ts

@@ -1,5 +1,13 @@
+import type {
+  BuiltinSynthBinding,
+  Sf2InstrumentConfig,
+  Sf2ProgramStatus,
+  SynthPatch,
+} from './instrument_types';
 import {
   assertProjectMidiEvents,
+  normalizeSynthInstrument,
+  projectAutomationPointValue,
   projectAutomationTargetKindValue,
   projectLoopModeValue,
   projectMidi1Event,
@@ -9,7 +17,6 @@ import {
   type WasmProject,
 } from './project_internal';
 import type {
-  BuiltinSynthBinding,
   ExternalSeparatedStemImportRequest,
   ExternalSeparatedStemImportResult,
   MidiCcLearnOptions,
@@ -35,22 +42,53 @@ import type {
   ProjectMidiCcBinding,
   ProjectMidiClipResult,
   ProjectMidiEvent,
+  ProjectMidiFxBakeRequest,
+  ProjectMidiFxBakeResult,
+  ProjectMidiFxPreviewRequest,
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
   ProjectSource,
   ProjectTempoCandidate,
+  ProjectTempoOptions,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
   ProjectTrack,
   ProjectTrackDesc,
   ProjectTrackKind,
+  ProjectTranscribeRequest,
   ProjectWarpMapDesc,
   ProjectWarpMode,
-  Sf2InstrumentConfig,
-  Sf2ProgramStatus,
-  SynthPatch,
 } from './project_types';
+import {
+  assertBoundedInteger,
+  assertNibble,
+  assertSampleRate,
+  assertSamples,
+  assertU7,
+} from './validation';
+
+/**
+ * Folds the positional and request call forms of `bakeMidiFx` into one shape,
+ * so defaults, validation and errors cannot diverge between them.
+ */
+function normalizeMidiFxBakeRequest(
+  clipIdOrRequest: number | ProjectMidiFxBakeRequest,
+  configJson?: string,
+): Required<ProjectMidiFxBakeRequest> {
+  if (typeof clipIdOrRequest === 'number') {
+    return {
+      clipId: clipIdOrRequest,
+      configJson: configJson ?? '',
+      withSourceIndex: false,
+    };
+  }
+  return {
+    clipId: clipIdOrRequest.clipId,
+    configJson: clipIdOrRequest.configJson,
+    withSourceIndex: clipIdOrRequest.withSourceIndex ?? false,
+  };
+}
 
 function validateAssistSidecarUint32(value: unknown, field: string): number {
   if (
@@ -87,6 +125,52 @@ function validateAssistSidecarModuleId(value: unknown): string {
   return value;
 }
 
+const MIDI2_U16_MAX = 0xffff;
+const MIDI2_U32_MAX = 0xffffffff;
+
+// UMP MIDI-2.0 channel-voice packet (message type 0x4). Canonical layout is
+// sonare::midi::make_midi2_* (C-ABI sonare_midi2_*); the golden vectors in
+// midi2-ump.test.ts lock this copy against it.
+function midi2Event(
+  fnName: string,
+  ppq: number,
+  group: number,
+  opcode: number,
+  channel: number,
+  byte2: number,
+  byte3: number,
+  word1: number,
+): ProjectMidiEvent {
+  if (!Number.isFinite(ppq) || ppq < 0) {
+    throw new RangeError(`${fnName}: ppq must be a non-negative finite number`);
+  }
+  const g = assertNibble(fnName, group, 'group');
+  const ch = assertNibble(fnName, channel, 'channel');
+  const word0 =
+    ((0x4 << 28) | (g << 24) | (opcode << 20) | (ch << 16) | (byte2 << 8) | byte3) >>> 0;
+  return { ppq, data0: word0, data1: word1 >>> 0 };
+}
+
+function midi2U32(fnName: string, value: number, argName: string): number {
+  assertBoundedInteger(fnName, value, argName, 0, MIDI2_U32_MAX);
+  return value;
+}
+
+function midi2U16(fnName: string, value: number, argName: string): number {
+  assertBoundedInteger(fnName, value, argName, 0, MIDI2_U16_MAX);
+  return value;
+}
+
+function midi2I32(fnName: string, value: number, argName: string): number {
+  assertBoundedInteger(fnName, value, argName, -0x80000000, 0x7fffffff);
+  return value;
+}
+
+function midi2Byte(fnName: string, value: number, argName: string): number {
+  assertBoundedInteger(fnName, value, argName, 0, 0xff);
+  return value;
+}
+
 /**
  * Headless DAW project (control-thread-only arrangement model).
  *
@@ -115,6 +199,7 @@ function validateAssistSidecarModuleId(value: unknown): string {
  */
 export class Project {
   private native: WasmProject;
+  private released = false;
 
   constructor() {
     this.native = new (projectModule().Project)();
@@ -179,6 +264,233 @@ export class Project {
     return projectMidi1Event('Project.midiProgram', ppq, group, 0xc, channel, program, 0);
   }
 
+  /**
+   * Pack a MIDI 2.0 note-on event accepted by {@link setMidiEvents}.
+   * `velocity16` is the full 16-bit velocity (0 is a sounding note-on);
+   * `attributeType` 0 is none, 3 is pitch 7.9.
+   */
+  static midi2NoteOn(
+    ppq: number,
+    group: number,
+    channel: number,
+    note: number,
+    velocity16: number,
+    attributeType = 0,
+    attributeData = 0,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2NoteOn';
+    const n = assertU7(fn, note, 'note');
+    const vel = midi2U16(fn, velocity16, 'velocity16');
+    const type = midi2Byte(fn, attributeType, 'attributeType');
+    const data = midi2U16(fn, attributeData, 'attributeData');
+    return midi2Event(fn, ppq, group, 0x9, channel, n, type, ((vel << 16) | data) >>> 0);
+  }
+
+  /** Pack a MIDI 2.0 note-off event (`velocity16` is the full 16-bit release velocity). */
+  static midi2NoteOff(
+    ppq: number,
+    group: number,
+    channel: number,
+    note: number,
+    velocity16 = 0,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2NoteOff';
+    const n = assertU7(fn, note, 'note');
+    const vel = midi2U16(fn, velocity16, 'velocity16');
+    return midi2Event(fn, ppq, group, 0x8, channel, n, 0, (vel << 16) >>> 0);
+  }
+
+  /** Pack a MIDI 2.0 control-change event (`value32` is the full 32-bit value). */
+  static midi2Cc(
+    ppq: number,
+    group: number,
+    channel: number,
+    controller: number,
+    value32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2Cc';
+    const c = assertU7(fn, controller, 'controller');
+    return midi2Event(fn, ppq, group, 0xb, channel, c, 0, midi2U32(fn, value32, 'value32'));
+  }
+
+  /** Pack a MIDI 2.0 poly-pressure event (`pressure32` is the full 32-bit pressure). */
+  static midi2PolyPressure(
+    ppq: number,
+    group: number,
+    channel: number,
+    note: number,
+    pressure32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2PolyPressure';
+    const n = assertU7(fn, note, 'note');
+    return midi2Event(fn, ppq, group, 0xa, channel, n, 0, midi2U32(fn, pressure32, 'pressure32'));
+  }
+
+  /** Pack a MIDI 2.0 channel-pressure event (`pressure32` is the full 32-bit pressure). */
+  static midi2ChannelPressure(
+    ppq: number,
+    group: number,
+    channel: number,
+    pressure32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2ChannelPressure';
+    return midi2Event(fn, ppq, group, 0xd, channel, 0, 0, midi2U32(fn, pressure32, 'pressure32'));
+  }
+
+  /** Pack a MIDI 2.0 pitch-bend event (`bend32` is unsigned 32-bit, center = 0x80000000). */
+  static midi2PitchBend(
+    ppq: number,
+    group: number,
+    channel: number,
+    bend32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2PitchBend';
+    return midi2Event(fn, ppq, group, 0xe, channel, 0, 0, midi2U32(fn, bend32, 'bend32'));
+  }
+
+  /**
+   * Pack a MIDI 2.0 program-change event. The bank travels in the same message
+   * and is applied only when `bankValid` is true.
+   */
+  static midi2Program(
+    ppq: number,
+    group: number,
+    channel: number,
+    program: number,
+    bankValid = false,
+    bankMsb = 0,
+    bankLsb = 0,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2Program';
+    const p = assertU7(fn, program, 'program');
+    const msb = assertU7(fn, bankMsb, 'bankMsb');
+    const lsb = assertU7(fn, bankLsb, 'bankLsb');
+    const word1 = ((p << 24) | (msb << 8) | lsb) >>> 0;
+    return midi2Event(fn, ppq, group, 0xc, channel, 0, bankValid ? 1 : 0, word1);
+  }
+
+  /** Pack a MIDI 2.0 registered controller (RPN) event. */
+  static midi2RegisteredController(
+    ppq: number,
+    group: number,
+    channel: number,
+    bank: number,
+    index: number,
+    value32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2RegisteredController';
+    const b = assertU7(fn, bank, 'bank');
+    const i = assertU7(fn, index, 'index');
+    return midi2Event(fn, ppq, group, 0x2, channel, b, i, midi2U32(fn, value32, 'value32'));
+  }
+
+  /** Pack a MIDI 2.0 assignable controller (NRPN) event. */
+  static midi2AssignableController(
+    ppq: number,
+    group: number,
+    channel: number,
+    bank: number,
+    index: number,
+    value32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2AssignableController';
+    const b = assertU7(fn, bank, 'bank');
+    const i = assertU7(fn, index, 'index');
+    return midi2Event(fn, ppq, group, 0x3, channel, b, i, midi2U32(fn, value32, 'value32'));
+  }
+
+  /** Pack a MIDI 2.0 relative registered controller event (`delta32` is a signed change). */
+  static midi2RelativeRegisteredController(
+    ppq: number,
+    group: number,
+    channel: number,
+    bank: number,
+    index: number,
+    delta32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2RelativeRegisteredController';
+    const b = assertU7(fn, bank, 'bank');
+    const i = assertU7(fn, index, 'index');
+    return midi2Event(fn, ppq, group, 0x4, channel, b, i, midi2I32(fn, delta32, 'delta32'));
+  }
+
+  /** Pack a MIDI 2.0 relative assignable controller event (`delta32` is a signed change). */
+  static midi2RelativeAssignableController(
+    ppq: number,
+    group: number,
+    channel: number,
+    bank: number,
+    index: number,
+    delta32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2RelativeAssignableController';
+    const b = assertU7(fn, bank, 'bank');
+    const i = assertU7(fn, index, 'index');
+    return midi2Event(fn, ppq, group, 0x5, channel, b, i, midi2I32(fn, delta32, 'delta32'));
+  }
+
+  /** Pack a MIDI 2.0 registered per-note controller event (`index` is 0..255). */
+  static midi2RegisteredPerNoteController(
+    ppq: number,
+    group: number,
+    channel: number,
+    note: number,
+    index: number,
+    value32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2RegisteredPerNoteController';
+    const n = assertU7(fn, note, 'note');
+    const i = midi2Byte(fn, index, 'index');
+    return midi2Event(fn, ppq, group, 0x0, channel, n, i, midi2U32(fn, value32, 'value32'));
+  }
+
+  /** Pack a MIDI 2.0 assignable per-note controller event (`index` is 0..255). */
+  static midi2AssignablePerNoteController(
+    ppq: number,
+    group: number,
+    channel: number,
+    note: number,
+    index: number,
+    value32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2AssignablePerNoteController';
+    const n = assertU7(fn, note, 'note');
+    const i = midi2Byte(fn, index, 'index');
+    return midi2Event(fn, ppq, group, 0x1, channel, n, i, midi2U32(fn, value32, 'value32'));
+  }
+
+  /** Pack a MIDI 2.0 per-note pitch-bend event (`bend32` is unsigned 32-bit, center = 0x80000000). */
+  static midi2PerNotePitchBend(
+    ppq: number,
+    group: number,
+    channel: number,
+    note: number,
+    bend32: number,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2PerNotePitchBend';
+    const n = assertU7(fn, note, 'note');
+    return midi2Event(fn, ppq, group, 0x6, channel, n, 0, midi2U32(fn, bend32, 'bend32'));
+  }
+
+  /**
+   * Pack a MIDI 2.0 per-note management event. `detach` sets the D flag
+   * (detach per-note controllers from voices already sounding on `note`);
+   * `reset` sets the S flag (reset the note's per-note controllers).
+   */
+  static midi2PerNoteManagement(
+    ppq: number,
+    group: number,
+    channel: number,
+    note: number,
+    detach = false,
+    reset = false,
+  ): ProjectMidiEvent {
+    const fn = 'Project.midi2PerNoteManagement';
+    const n = assertU7(fn, note, 'note');
+    const flags = (detach ? 0x02 : 0) | (reset ? 0x01 : 0);
+    return midi2Event(fn, ppq, group, 0xf, channel, n, flags, 0);
+  }
+
   /** Return the General MIDI instrument name for `program`, or `null` when out of range. */
   static gmInstrumentName(program: number): string | null {
     return projectModule().midiGmInstrumentName(program);
@@ -310,9 +622,7 @@ export class Project {
     channel: number,
     bend: number,
   ): ProjectMidiEvent {
-    if (!Number.isInteger(bend) || bend < 0 || bend > 0x3fff) {
-      throw new RangeError('Project.midiPitchBend: bend must be an integer in [0, 16383]');
-    }
+    assertBoundedInteger('Project.midiPitchBend', bend, 'bend', 0, 0x3fff);
     return projectMidi1Event(
       'Project.midiPitchBend',
       ppq,
@@ -370,7 +680,11 @@ export class Project {
     return this.native.toJson();
   }
 
-  /** Set the project sample rate in Hz. Must be > 0. */
+  /**
+   * Set the project sample rate in Hz. Must be in `[8000, 384000]`; anything
+   * outside that range throws. Applied through the edit history, so it is
+   * undoable.
+   */
   setSampleRate(sampleRate: number): void {
     this.native.setSampleRate(sampleRate);
   }
@@ -462,7 +776,24 @@ export class Project {
     this.native.setTrackMidiDestination(trackId, destinationId);
   }
 
-  /** Set a track's linear playback gain (1.0 = unity; >= 0) via an undoable edit. */
+  /**
+   * Set a track's linear playback gain (1.0 = unity; >= 0) via an undoable edit.
+   *
+   * The value reaches the track's audio and MIDI alike, but the stage it lands
+   * on follows the track's channel strip. A strip bound by this track alone
+   * (including one synthesized for an unbound track) carries the controls on its
+   * own fader and panner. A strip several tracks share processes their sum and
+   * carries none of them; each track applies its controls upstream instead — on
+   * its own clip schedules for audio, on its track lane for MIDI.
+   *
+   * A MIDI track's gain/pan on a shared strip ride the track lane, which is fed
+   * per source track only by an instrument that preserves source-track identity
+   * (see {@link setTrackMidiDestination}). An opaque host-callback instrument, or
+   * one reporting non-zero latency, renders one buffer per destination and has no
+   * per-track stage on a shared strip, so its gain/pan do not reach the bounce
+   * there; bind such an instrument to a track with an exclusive strip. Mute and
+   * solo are unaffected: a silenced MIDI track schedules no events at all.
+   */
   setTrackGain(trackId: number, gain: number): void {
     this.native.setTrackGain(trackId, gain);
   }
@@ -477,7 +808,17 @@ export class Project {
     this.native.setTrackSolo(trackId, solo);
   }
 
-  /** Set a track's stereo balance in [-1, +1] (0 = center) via an undoable edit. */
+  /**
+   * Set a track's stereo balance in [-1, +1] (0 = center) via an undoable edit.
+   *
+   * See {@link setTrackGain} for which stage a track's controls land on. The pan
+   * law that shapes the balance belongs to that stage: the strip's configured law
+   * on a channel strip and on the clips of an audio track sharing a strip, and
+   * the track lane's law for a MIDI track sharing a strip (the law of whatever
+   * strip the host bound to that lane, or a linear balance when none is bound).
+   * Every law is normalized so a centered track stays at unity and only the away
+   * channel is attenuated, so the difference is a taper, not a level offset.
+   */
   setTrackPan(trackId: number, pan: number): void {
     this.native.setTrackPan(trackId, pan);
   }
@@ -518,7 +859,18 @@ export class Project {
     this.native.setMaxHistoryBytes(bytes);
   }
 
-  /** Replace a MIDI clip's entire event list. */
+  /**
+   * Replace a MIDI clip's entire event list.
+   *
+   * @remarks
+   * Drops the clip's SysEx, which {@link importSmf} and {@link exportSmf} both
+   * keep. A clip's SysEx payloads sit beside the event list and are reached by
+   * a handle {@link ProjectMidiEvent} does not carry, so replacing the list
+   * leaves nothing referring to them: a GS setup block that survives an import
+   * and an export byte for byte is gone after one call here. Nothing reads the
+   * handles back either, so a caller that must keep the setup edits the
+   * exported file rather than the event list.
+   */
   setMidiEvents(
     clipId: number,
     events: ReadonlyArray<ProjectMidiEvent | readonly [number, number, number]>,
@@ -536,8 +888,15 @@ export class Project {
     return this.native.importSmf(data);
   }
 
-  /** Export the project's tempo map + MIDI clips to an SMF byte buffer. */
-  exportSmf(): Uint8Array {
+  /**
+   * Export the project's tempo map + MIDI clips to an SMF byte buffer.
+   *
+   * @remarks
+   * The buffer owns a plain `ArrayBuffer`, which is what the `Blob` / `File`
+   * constructors accept — so `new Blob([project.exportSmf()])` compiles without
+   * a copy through `new Uint8Array(...)` first.
+   */
+  exportSmf(): Uint8Array<ArrayBuffer> {
     return this.native.exportSmf();
   }
 
@@ -555,8 +914,12 @@ export class Project {
    * Export the project's tempo map + MIDI clips to a MIDI 2.0 Clip File
    * (`SMF2CLIP`) byte buffer. MIDI 2.0-only events are written without loss —
    * prefer this over {@link exportSmf} when MIDI 2.0 fidelity matters.
+   *
+   * @remarks
+   * As with {@link exportSmf}, the buffer owns a plain `ArrayBuffer` and goes
+   * straight into a `Blob`.
    */
-  exportClipFile(): Uint8Array {
+  exportClipFile(): Uint8Array<ArrayBuffer> {
     return this.native.exportClipFile();
   }
 
@@ -584,8 +947,33 @@ export class Project {
    * Destructively bake a MIDI-FX chain into all stored events. Large clips are
    * drained without truncation; failure leaves the original clip unchanged.
    */
-  bakeMidiFx(clipId: number, configJson: string): void {
-    this.native.bakeMidiFx(clipId, configJson);
+  bakeMidiFx(clipId: number, configJson: string): void;
+  /**
+   * Request form. Setting `withSourceIndex` also returns per-event provenance,
+   * so a selection or an editorial annotation can be carried across the bake.
+   */
+  bakeMidiFx(request: ProjectMidiFxBakeRequest): ProjectMidiFxBakeResult;
+  bakeMidiFx(
+    clipIdOrRequest: number | ProjectMidiFxBakeRequest,
+    configJson?: string,
+  ): ProjectMidiFxBakeResult {
+    const request = normalizeMidiFxBakeRequest(clipIdOrRequest, configJson);
+    if (!request.withSourceIndex) {
+      this.native.bakeMidiFx(request.clipId, request.configJson);
+      return {};
+    }
+    return {
+      sourceIndex: this.native.bakeMidiFxWithSourceIndex(request.clipId, request.configJson),
+    };
+  }
+
+  /**
+   * Count the events {@link bakeMidiFx} would produce for this clip and
+   * configuration, without mutating the project. The transform is
+   * deterministic, so the count matches what the bake goes on to produce.
+   */
+  previewMidiFxCount(request: ProjectMidiFxPreviewRequest): number {
+    return this.native.previewMidiFxCount(request.clipId, request.configJson);
   }
 
   /** Backward alias for {@link bakeMidiFx}. */
@@ -603,19 +991,62 @@ export class Project {
     return this.native.validateMidiNotes(clipId);
   }
 
+  /**
+   * Transcribe mono audio straight into a MIDI clip's event list, **replacing**
+   * whatever it held — exactly as {@link setMidiEvents} does.
+   *
+   * The PPQ grid is this project's own tempo map, which is why there is no
+   * `tempoBpm` field: a project whose tempo was installed by {@link autoTempo}
+   * transcribes onto that map rather than onto a second, separately detected
+   * tempo. Use the standalone `transcribe` when you want events without a
+   * project.
+   *
+   * Quantizing, tempo detection and key/chord annotation are not done here —
+   * see `transcribe` for what each belongs to.
+   *
+   * @returns the number of notes written (half the events)
+   * @throws {RangeError} on empty `samples`, a non-finite sample, or a
+   *   `sampleRate` outside `[8000, 384000]`
+   * @throws {SonareError} `InvalidParameter` when `clipId` is unknown or not a
+   *   MIDI clip, or on an option outside its domain; `NotSupported` when the
+   *   library was built without the pitch editor
+   */
+  transcribeToClip(request: ProjectTranscribeRequest): number {
+    assertSamples('Project.transcribeToClip', request.samples, true);
+    assertSampleRate('Project.transcribeToClip', request.sampleRate);
+    return this.native.transcribeToClip(
+      request.clipId,
+      request.samples,
+      request.sampleRate,
+      request,
+    );
+  }
+
   /** Return ranked tempo-octave and detected-meter candidates without editing. */
-  analyzeTempo(audio: Float32Array, sampleRate: number): ProjectTempoCandidate[] {
-    return this.native.analyzeTempo(audio, sampleRate);
+  analyzeTempo(
+    audio: Float32Array,
+    sampleRate: number,
+    options?: ProjectTempoOptions,
+  ): ProjectTempoCandidate[] {
+    return this.native.analyzeTempo(audio, sampleRate, options);
   }
 
-  /** Detect and install a ranked tempo candidate; optionally apply detected meter. */
+  /**
+   * Detect and install a ranked tempo candidate; optionally apply detected meter.
+   *
+   * @remarks
+   * `candidateIndex` indexes the ranking {@link analyzeTempo} produced, so pair
+   * the two on the same `options`. Read the installed map back with
+   * {@link tempoSegmentCount} and {@link tempoSegmentByIndex}.
+   */
   autoTempo(
     audio: Float32Array,
     sampleRate: number,
     candidateIndex = 0,
     applyTimeSignatures = false,
+    options?: ProjectTempoOptions,
   ): number {
-    return this.native.autoTempo(audio, sampleRate, candidateIndex, applyTimeSignatures);
+    return this.native.autoTempo(audio, sampleRate, candidateIndex, applyTimeSignatures, options);
   }
 
   /** Snap to a bar (`division=0`), beat (`1`), or beat subdivision (`2+`). */
@@ -677,9 +1108,9 @@ export class Project {
 
   /**
    * Compile + render the project offline, routing MIDI tracks through the
-   * patch-driven NativeSynth — the full synthesizer (subtractive / FM /
-   * Karplus-Strong / modal / additive / percussion / extended-waveguide-piano
-   * engines plus the realism layer). Pass a {@link SynthPatch}, a preset-name
+   * patch-driven NativeSynth — the full synthesizer (every
+   * {@link SynthEngineMode} engine plus the realism layer; the modes are
+   * enumerated by {@link SYNTH_ENGINE_MODES}). Pass a {@link SynthPatch}, a preset-name
    * string (`'saw-lead'` / `'va:saw-lead'`; see {@link synthPresetNames}), or
    * an array of either; each object entry may carry `destinationId` (default
    * 0) and `useGmPrograms` (default `false`) binding conveniences, neither of
@@ -690,12 +1121,19 @@ export class Project {
    * both create one default binding. Use an explicitly empty array `[]` (or
    * runtime `null`) for zero bindings. Unknown preset names throw.
    * Deterministic for a fixed project + options + patch.
+   *
+   * An `engineMode: 'sample'` patch reads its PCM from the {@link SampleBank}
+   * passed as `sampleBank`; the bank must still be alive when the bounce runs,
+   * and one bound without a bank renders silence.
    */
   bounceWithSynthInstrument(
     instrument: SynthPatch | string | ReadonlyArray<SynthPatch | string> = {},
     options: ProjectBounceOptions = {},
   ): Float32Array {
-    return this.native.bounceWithSynthInstrument(instrument, options);
+    const normalized = Array.isArray(instrument)
+      ? instrument.map((entry) => normalizeSynthInstrument(entry))
+      : normalizeSynthInstrument(instrument);
+    return this.native.bounceWithSynthInstrument(normalized, options);
   }
 
   /**
@@ -845,7 +1283,10 @@ export class Project {
     if (desc.targetParamId === 0) {
       throw new RangeError('project automation lane targetParamId must be non-zero');
     }
-    const nativeDesc: ProjectAutomationLaneDesc = { ...desc };
+    const nativeDesc: ProjectAutomationLaneDesc = {
+      ...desc,
+      points: desc.points.map(projectAutomationPointValue),
+    };
     if (Object.keys(desc).includes('targetKind')) {
       nativeDesc.targetKind = projectAutomationTargetKindValue(
         desc.targetKind as ProjectAutomationTargetKind,
@@ -863,7 +1304,10 @@ export class Project {
     if (desc.targetParamId === 0) {
       throw new RangeError('project automation lane targetParamId must be non-zero');
     }
-    const nativeDesc: ProjectAutomationLaneDesc = { ...desc };
+    const nativeDesc: ProjectAutomationLaneDesc = {
+      ...desc,
+      points: desc.points.map(projectAutomationPointValue),
+    };
     if (Object.keys(desc).includes('targetKind')) {
       nativeDesc.targetKind = projectAutomationTargetKindValue(
         desc.targetKind as ProjectAutomationTargetKind,
@@ -1047,6 +1491,28 @@ export class Project {
     return this.native.tempoSegmentCount();
   }
 
+  /**
+   * Reads a tempo segment by index, in stored order.
+   *
+   * @param index - Zero-based index below {@link tempoSegmentCount}
+   * @returns The segment, in the shape {@link setTempoSegments} accepts
+   * @throws When the index is at or past the count
+   */
+  tempoSegmentByIndex(index: number): ProjectTempoSegment {
+    return this.native.tempoSegmentByIndex(index);
+  }
+
+  /**
+   * Reads a time-signature segment by index, in stored order.
+   *
+   * @param index - Zero-based index below {@link timeSignatureCount}
+   * @returns The segment, in the shape {@link setTimeSignatures} accepts
+   * @throws When the index is at or past the count
+   */
+  timeSignatureByIndex(index: number): ProjectTimeSignatureSegment {
+    return this.native.timeSignatureByIndex(index);
+  }
+
   /** Number of time-signature segments on the project. */
   timeSignatureCount(): number {
     return this.native.timeSignatureCount();
@@ -1064,15 +1530,22 @@ export class Project {
 
   /**
    * Compile diagnostics produced by the most recent bounce on this project
-   * (e.g. MIDI clips rendering silently without a bound instrument). When no
-   * bounce has run, the result is empty with `hasTimeline` set.
+   * (e.g. MIDI clips rendering silently without a bound instrument). On a
+   * project no bounce has ever run on, the result is empty in full:
+   * `hasTimeline` is `false` and `diagnostics` is empty. A failed bounce is
+   * distinguishable from that state, because a bounce only loses its timeline
+   * through an error diagnostic and so always reports at least one.
    */
   lastBounceCompileResult(): ProjectCompileResult {
     return this.native.lastBounceCompileResult();
   }
 
-  /** Release the underlying WASM object. Safe to call only once. */
+  /** Release the underlying WASM object. Idempotent, as the Node facade is. */
   delete(): void {
+    if (this.released) {
+      return;
+    }
+    this.released = true;
     this.native.delete();
   }