@libraz/libsonare 1.7.2 → 1.8.0

package/src/worklet/engine.ts

@@ -22,6 +22,7 @@ import type {
   MidiCcBindOptions,
   PanLaw,
   PanMode,
+  SidechainSourceKind,
 } from '../index';
 import { RealtimeEngine } from '../index';
 import { createOpfsClipPageProvider, type OpfsClipPageProviderBinding } from '../opfs_clip_pages';
@@ -34,7 +35,7 @@ import type { EngineClipContext } from './engine-clips';
 import * as clips from './engine-clips';
 import type { EngineMarkerContext } from './engine-markers';
 import * as markers from './engine-markers';
-import type { EngineMixerContext } from './engine-mixer-facade';
+import type { EngineMixerContext, InsertParamOverrideMap } from './engine-mixer-facade';
 import * as mixer from './engine-mixer-facade';
 import { SonareRealtimeEngineNode } from './engine-node';
 import { buildTransportFacade, type CaptureOptions } from './engine-offline';
@@ -94,6 +95,7 @@ export class SonareEngine {
   private readonly offlineBlockSize: number;
   private readonly offlineChannelCount: number;
   private readonly automationLanes = new Map<number, EngineAutomationPoint[]>();
+  private readonly insertAutomationIdsByTarget = new Map<string, Set<number>>();
   private readonly clips = new Map<number, EngineClip>();
   private readonly midiClips = new Map<number, EngineMidiClipSchedule>();
   private readonly markers = new Map<number, EngineMarker>();
@@ -104,9 +106,18 @@ export class SonareEngine {
     string,
     { trackId: number; insertIndex: number; sourceTrackId: number }
   >();
+  private readonly busSidechains = new Map<
+    string,
+    { busId: number; insertIndex: number; sourceKind: number; sourceId: number }
+  >();
+  private readonly masterSidechains = new Map<
+    number,
+    { insertIndex: number; sourceKind: number; sourceId: number }
+  >();
   private readonly buses: EngineBus[] = [];
   private readonly trackStripJson = new Map<number, string>();
   private readonly busStripJson = new Map<number, string>();
+  private readonly insertParamOverrides: InsertParamOverrideMap = new Map();
   private masterStripJson: string | undefined;
   private captureConfig: Omit<SonareEngineSyncCaptureMessage, 'type'> | undefined;
   private tempoBpm = 120;
@@ -320,12 +331,17 @@ export class SonareEngine {
     insertIndex: number,
     paramName: string,
   ): number {
-    return parameter.resolveTrackInsertAutomationId(
+    const id = parameter.resolveTrackInsertAutomationId(
       this.parameterContext,
       target,
       insertIndex,
       paramName,
     );
+    if (id >= 0) {
+      const trackId = this.trackLaneIds[this.ensureTrackLane(target)];
+      this.rememberInsertAutomationId({ kind: 'track', trackId }, id);
+    }
+    return id;
   }
 
   /**
@@ -337,7 +353,15 @@ export class SonareEngine {
    * @returns Reserved insert-automation id, or -1 when insert/key unknown.
    */
   resolveMasterInsertAutomationId(insertIndex: number, paramName: string): number {
-    return parameter.resolveMasterInsertAutomationId(this.parameterContext, insertIndex, paramName);
+    const id = parameter.resolveMasterInsertAutomationId(
+      this.parameterContext,
+      insertIndex,
+      paramName,
+    );
+    if (id >= 0) {
+      this.rememberInsertAutomationId({ kind: 'master' }, id);
+    }
+    return id;
   }
 
   /**
@@ -351,12 +375,30 @@ export class SonareEngine {
    * @returns Reserved insert-automation id, or -1 when bus/insert/key unknown.
    */
   resolveBusInsertAutomationId(busId: number, insertIndex: number, paramName: string): number {
-    return parameter.resolveBusInsertAutomationId(
+    const id = parameter.resolveBusInsertAutomationId(
       this.parameterContext,
       busId,
       insertIndex,
       paramName,
     );
+    if (id >= 0) {
+      this.rememberInsertAutomationId({ kind: 'bus', busId }, id);
+    }
+    return id;
+  }
+
+  /**
+   * Resolves a hosted instrument's continuous parameter to its reserved
+   * instrument-automation id, so an instrument parameter follows a breakpoint
+   * lane at audio-block precision like a strip insert. Bind the instrument
+   * (`setSynthInstrument`) before resolving.
+   *
+   * @param destinationId MIDI destination the instrument is bound to.
+   * @param paramName Instrument JSON-key parameter name (e.g. `cutoffHz`).
+   * @returns Reserved instrument-automation id, or -1 when destination/key unknown.
+   */
+  resolveInstrumentAutomationId(destinationId: number, paramName: string): number {
+    return parameter.resolveInstrumentAutomationId(this.parameterContext, destinationId, paramName);
   }
 
   /**
@@ -397,11 +439,19 @@ export class SonareEngine {
   }
 
   setStripGain(target: string | number, db: number): boolean {
-    return this.sendSmoothedParam(this.stripParamId(target, ENGINE_MIXER_PARAM_FADER_DB), db);
+    const sent = this.sendSmoothedParam(this.stripParamId(target, ENGINE_MIXER_PARAM_FADER_DB), db);
+    if (sent && target === 'master') {
+      strips.cacheMasterStripScalar(this.stripContext, 'faderDb', db);
+    }
+    return sent;
   }
 
   setStripPan(target: string | number, pan: number): boolean {
-    return this.sendSmoothedParam(this.stripParamId(target, ENGINE_MIXER_PARAM_PAN), pan);
+    const sent = this.sendSmoothedParam(this.stripParamId(target, ENGINE_MIXER_PARAM_PAN), pan);
+    if (sent && target === 'master') {
+      strips.cacheMasterStripScalar(this.stripContext, 'pan', pan);
+    }
+    return sent;
   }
 
   /**
@@ -448,6 +498,31 @@ export class SonareEngine {
     mixer.setTrackBuses(this.mixerContext, buses);
   }
 
+  /**
+   * 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 {
+    mixer.setBusSidechain(this.mixerContext, busId, insertIndex, 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 {
+    mixer.setMasterSidechain(this.mixerContext, insertIndex, sourceKind, sourceId);
+  }
+
   setBusGain(busId: number, db: number): boolean {
     return mixer.setBusGain(this.mixerContext, busId, db);
   }
@@ -455,8 +530,17 @@ export class SonareEngine {
   setTrackStripJson(target: string | number, sceneJson: string): void {
     const laneIndex = this.ensureTrackLane(target);
     const trackId = this.trackLaneIds[laneIndex];
-    strips.setTrackStripJson(this.stripContext, trackId, sceneJson, this.trackStripJson);
-    this.syncMixer();
+    const { resetInserts } = strips.setTrackStripJson(
+      this.stripContext,
+      trackId,
+      sceneJson,
+      this.trackStripJson,
+    );
+    if (resetInserts) {
+      this.clearInsertAutomationLanes({ kind: 'track', trackId });
+    }
+    mixer.pruneStripSidechains(this.mixerContext, { kind: 'track', trackId }, sceneJson);
+    this.syncMixer(resetInserts ? [{ kind: 'track', trackId }] : []);
   }
 
   setTrackStripEqBand(target: string | number, bandIndex: number, band: EqBand | string): void {
@@ -541,9 +625,18 @@ export class SonareEngine {
   }
 
   setMasterStripJson(sceneJson: string): void {
-    this.offlineEngine.setMasterStripJson(sceneJson);
+    const target = { kind: 'master' } as const;
+    const resetInserts =
+      (this.masterStripJson !== undefined && this.masterStripJson !== sceneJson) ||
+      mixer.hasInsertParamOverrides(this.insertParamOverrides, target);
+    mixer.applyFullStripJson(this.offlineEngine, target, sceneJson, resetInserts);
+    if (resetInserts) {
+      this.clearInsertAutomationLanes(target);
+    }
+    mixer.pruneStripSidechains(this.mixerContext, target, sceneJson);
+    mixer.clearInsertParamOverrides(this.insertParamOverrides, target);
     this.masterStripJson = sceneJson;
-    this.syncMixer();
+    this.syncMixer(resetInserts ? [target] : []);
   }
 
   setMasterStripEqBand(bandIndex: number, band: EqBand | string): void {
@@ -572,6 +665,58 @@ export class SonareEngine {
     strips.setBusStripInsertParamByName(this.stripContext, busId, insertIndex, paramName, value);
   }
 
+  /**
+   * Bus-strip counterpart of {@link setStripInsertBypassed}. A bus is addressed
+   * by its numeric id, which the `target` of the track/master form cannot
+   * express, so it is its own method exactly like
+   * {@link setBusStripInsertParamByName}. Bypassing keeps the insert's internal
+   * state (reverb tail, compressor envelope) unless `resetOnBypass` is set;
+   * re-posting the bus scene JSON, the only workaround before this existed,
+   * rebuilds the chain and loses it.
+   */
+  setBusStripInsertBypassed(
+    busId: number,
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass = false,
+  ): void {
+    this.ensureBus(busId);
+    strips.setBusStripInsertBypassed(
+      this.stripContext,
+      busId,
+      insertIndex,
+      bypassed,
+      resetOnBypass,
+    );
+  }
+
+  /** Bus-strip counterpart of {@link setTrackStripEqBand}. */
+  setBusStripEqBand(busId: number, bandIndex: number, band: EqBand | string): void {
+    this.ensureBus(busId);
+    strips.setBusStripEqBand(this.stripContext, busId, bandIndex, band);
+  }
+
+  /** Bus-strip counterpart of {@link setTrackStripPan}; refused on a surround bus. */
+  setBusStripPan(busId: number, pan: number): void {
+    this.ensureBus(busId);
+    strips.setBusStripPan(this.stripContext, busId, pan);
+  }
+
+  setBusStripPanLaw(busId: number, panLaw: PanLaw | number): void {
+    this.ensureBus(busId);
+    strips.setBusStripPanLaw(this.stripContext, busId, panLaw);
+  }
+
+  setBusStripPanMode(busId: number, panMode: PanMode | number): void {
+    this.ensureBus(busId);
+    strips.setBusStripPanMode(this.stripContext, busId, panMode);
+  }
+
+  setBusStripDualPan(busId: number, leftPan: number, rightPan: number): void {
+    this.ensureBus(busId);
+    strips.setBusStripDualPan(this.stripContext, busId, leftPan, rightPan);
+  }
+
   setStripInsertParamByName(
     target: string | number,
     insertIndex: number,
@@ -664,6 +809,52 @@ export class SonareEngine {
     return { binding, provider: binding.provider };
   }
 
+  /**
+   * Sets the clip-page look-ahead window in timeline frames on both the worklet
+   * engine and this thread's offline engine.
+   *
+   * The audio thread reports the pages it is *about to* read that are not
+   * resident yet, so the sliding-window streamer can service them before the
+   * playhead 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 that was not primed.
+   *
+   * Defaults to half a second at the engine's sample rate. `0` disables it.
+   * Safe to call during playback.
+   */
+  setClipPagePrefetchFrames(frames: number): void {
+    if (this.destroyed) {
+      throw new Error('SonareEngine is destroyed.');
+    }
+    if (!Number.isFinite(frames) || frames < 0) {
+      throw new Error('clip page prefetch frames must be a finite value >= 0.');
+    }
+    this.offlineEngine.setClipPagePrefetchFrames(frames);
+    this.postSync({ type: 'syncClipPagePrefetchFrames', frames });
+  }
+
+  /**
+   * Sets the number of concurrent time-stretch voices on both this thread's
+   * offline engine and the live worklet engine. `voices` must be an integer
+   * in `[0, 64]`; a non-integer, negative, or larger value throws and leaves
+   * the capacity unchanged on both engines. Default is 8. Capacity 0 disables
+   * time-stretch, so every warped clip plays resampled instead. A change
+   * applied while the engine is running restarts the splice state of any clip
+   * stretching through a voice at that moment.
+   */
+  setWarpVoiceCapacity(voices: number): void {
+    if (this.destroyed) {
+      throw new Error('SonareEngine is destroyed.');
+    }
+    this.offlineEngine.setWarpVoiceCapacity(voices);
+    this.postSync({ type: 'syncWarpVoiceCapacity', voices });
+  }
+
+  /** Reads the current time-stretch voice capacity (default 8). */
+  warpVoiceCapacity(): number {
+    return this.offlineEngine.warpVoiceCapacity();
+  }
+
   addClip(
     trackId: string | number,
     buffer: Float32Array[] | ClipPageProvider,
@@ -703,6 +894,8 @@ export class SonareEngine {
       gain?: number;
       polyphony?: number;
       preferModelForModeledFamilies?: boolean;
+      clearBankRig?: boolean;
+      gsEfxRealization?: 'modern' | 'classic';
     } = {},
   ): void {
     strips.setSf2Instrument(this.stripContext, trackId, config);
@@ -776,6 +969,52 @@ export class SonareEngine {
     strips.pushMidiCc(this.stripContext, trackId, group, channel, controller, value, renderFrame);
   }
 
+  pushMidiPitchBend(
+    trackId: string | number,
+    group: number,
+    channel: number,
+    bend14: number,
+    renderFrame = -1,
+  ): void {
+    strips.pushMidiPitchBend(this.stripContext, trackId, group, channel, bend14, renderFrame);
+  }
+
+  pushMidiChannelPressure(
+    trackId: string | number,
+    group: number,
+    channel: number,
+    pressure: number,
+    renderFrame = -1,
+  ): void {
+    strips.pushMidiChannelPressure(
+      this.stripContext,
+      trackId,
+      group,
+      channel,
+      pressure,
+      renderFrame,
+    );
+  }
+
+  pushMidiPolyPressure(
+    trackId: string | number,
+    group: number,
+    channel: number,
+    note: number,
+    pressure: number,
+    renderFrame = -1,
+  ): void {
+    strips.pushMidiPolyPressure(
+      this.stripContext,
+      trackId,
+      group,
+      channel,
+      note,
+      pressure,
+      renderFrame,
+    );
+  }
+
   pushMidiUmp(trackId: string | number, word0: number, renderFrame = -1): void {
     strips.pushMidiUmp(this.stripContext, trackId, word0, renderFrame);
   }
@@ -860,6 +1099,58 @@ export class SonareEngine {
     });
   }
 
+  pushMidiInputPitchBend(
+    group: number,
+    channel: number,
+    bend14: number,
+    portTimeSamples = 0,
+  ): void {
+    this.offlineEngine.pushMidiInputPitchBend(group, channel, bend14, portTimeSamples);
+    this.postSync({
+      type: 'syncMidiInputPitchBend',
+      group,
+      channel,
+      data0: bend14,
+      data1: 0,
+      portTimeSamples,
+    });
+  }
+
+  pushMidiInputChannelPressure(
+    group: number,
+    channel: number,
+    pressure: number,
+    portTimeSamples = 0,
+  ): void {
+    this.offlineEngine.pushMidiInputChannelPressure(group, channel, pressure, portTimeSamples);
+    this.postSync({
+      type: 'syncMidiInputChannelPressure',
+      group,
+      channel,
+      data0: pressure,
+      data1: 0,
+      portTimeSamples,
+    });
+  }
+
+  pushMidiInputPolyPressure(
+    group: number,
+    channel: number,
+    note: number,
+    pressure: number,
+    portTimeSamples = 0,
+  ): void {
+    this.offlineEngine.pushMidiInputPolyPressure(group, channel, note, pressure, portTimeSamples);
+    this.postSync({
+      type: 'syncMidiInputPolyPressure',
+      group,
+      channel,
+      data0: note,
+      data1: pressure,
+      portTimeSamples,
+    });
+  }
+
   pushMidiPanic(renderFrame = -1): void {
     this.offlineEngine.pushMidiPanic(renderFrame);
     this.postSync({ type: 'syncMidiPanic', renderFrame });
@@ -1106,8 +1397,42 @@ export class SonareEngine {
     return mixer.mixerLanes(this.mixerContext);
   }
 
-  private syncMixer(): void {
-    mixer.syncMixer(this.mixerContext);
+  private syncMixer(forceInsertResets: mixer.StripJsonTarget[] = []): void {
+    mixer.syncMixer(this.mixerContext, false, forceInsertResets);
+  }
+
+  private insertAutomationTargetKey(target: mixer.StripJsonTarget): string {
+    return target.kind === 'track'
+      ? `track:${target.trackId}`
+      : target.kind === 'bus'
+        ? `bus:${target.busId}`
+        : 'master';
+  }
+
+  private rememberInsertAutomationId(target: mixer.StripJsonTarget, id: number): void {
+    const key = this.insertAutomationTargetKey(target);
+    const ids = this.insertAutomationIdsByTarget.get(key) ?? new Set<number>();
+    ids.add(id);
+    this.insertAutomationIdsByTarget.set(key, ids);
+  }
+
+  private clearInsertAutomationLanes(
+    target: mixer.StripJsonTarget,
+    forgetResolvedIds = false,
+  ): void {
+    const key = this.insertAutomationTargetKey(target);
+    const ids = this.insertAutomationIdsByTarget.get(key);
+    if (!ids) {
+      return;
+    }
+    for (const id of ids) {
+      if (this.automationLanes.has(id)) {
+        this.setAutomationLane(id, []);
+      }
+    }
+    if (forgetResolvedIds) {
+      this.insertAutomationIdsByTarget.delete(key);
+    }
   }
 
   private postInstrumentSync(message: SonareEngineInstrumentSyncMessage): void {
@@ -1138,22 +1463,17 @@ export class SonareEngine {
     if (this.destroyed) {
       return;
     }
-    try {
-      if (transfer && transfer.length > 0) {
-        this.realtimeNode.node.port.postMessage(message, transfer);
-      } else {
-        this.realtimeNode.node.port.postMessage(message);
-      }
-    } finally {
-      this.flushOfflineMirror();
+    if (transfer && transfer.length > 0) {
+      this.realtimeNode.node.port.postMessage(message, transfer);
+    } else {
+      this.realtimeNode.node.port.postMessage(message);
     }
   }
 
-  // The offline engine is a control-thread mirror. It has no render loop to
-  // drain its command ring, so drain it after each control operation. Never
-  // call this from the worklet/audio path: it is intentionally control-only.
+  // The control-only mirror applies due commands immediately while preserving
+  // scheduled ones for its next render block.
   private flushOfflineMirror(): void {
-    this.offlineEngine.flushControlCommands();
+    this.offlineEngine.applyCommandsDueNowPreservingFuture();
   }
 
   private sendMirroredCommand(
@@ -1175,16 +1495,25 @@ export class SonareEngine {
       trackSends: this.trackSends,
       trackOutputBus: this.trackOutputBus,
       laneSidechains: this.laneSidechains,
+      busSidechains: this.busSidechains,
+      masterSidechains: this.masterSidechains,
       buses: this.buses,
       trackStripJson: this.trackStripJson,
       busStripJson: this.busStripJson,
+      insertParamOverrides: this.insertParamOverrides,
+      flushOfflineMirror: () => this.flushOfflineMirror(),
       postSync: (message) => this.postSync(message),
       ensureTrackLane: (target) => this.ensureTrackLane(target),
       ensureBus: (busId) => this.ensureBus(busId),
       mixerLanes: () => this.mixerLanes(),
-      syncMixer: () => this.syncMixer(),
+      syncMixer: (forceInsertResets) => this.syncMixer(forceInsertResets),
+      clearInsertAutomationLanes: (target, forgetResolvedIds) =>
+        this.clearInsertAutomationLanes(target, forgetResolvedIds),
       sendSmoothedParam: (paramId, value) => this.sendSmoothedParam(paramId, value),
       getMasterStripJson: () => this.masterStripJson,
+      cacheMasterStripJson: (sceneJson) => {
+        this.masterStripJson = sceneJson;
+      },
     };
   }
 
@@ -1199,6 +1528,10 @@ export class SonareEngine {
       postInstrumentSync: (message) => this.postInstrumentSync(message),
       ensureTrackLane: (target) => this.ensureTrackLane(target),
       resolveTargetId: (target) => this.resolveTargetId(target),
+      readStripJson: (target) => mixer.cachedStripJson(this.mixerContext, target),
+      writeStripJson: (target, sceneJson) =>
+        mixer.cacheStripJson(this.mixerContext, target, sceneJson),
+      insertParamOverrides: this.insertParamOverrides,
     };
   }
 
@@ -1352,7 +1685,7 @@ export class SonareEngine {
   private ensureTrackLane(target: string | number): number {
     const trackId = this.resolveTargetId(target);
     if (!Number.isInteger(trackId) || trackId <= 0) {
-      throw new Error(`Invalid track id for mixer lane: ${String(target)}`);
+      throw new RangeError(`Invalid track id for mixer lane: ${String(target)}`);
     }
     const existing = this.trackLaneIds.indexOf(trackId);
     if (existing >= 0) {
@@ -1364,15 +1697,16 @@ export class SonareEngine {
   }
 
   private ensureBus(busId: number): number {
-    const resolved = Math.trunc(busId);
-    if (!Number.isInteger(resolved) || resolved <= 0) {
-      throw new Error(`Invalid bus id for mixer bus: ${String(busId)}`);
+    // Tested on the raw id: truncating first leaves the integrality check
+    // unreachable, and registers a bus under an id the caller never named.
+    if (!Number.isInteger(busId) || busId <= 0) {
+      throw new RangeError(`Invalid bus id for mixer bus: ${String(busId)}`);
     }
-    const existing = this.buses.findIndex((bus) => bus.busId === resolved);
+    const existing = this.buses.findIndex((bus) => bus.busId === busId);
     if (existing >= 0) {
       return existing;
     }
-    this.buses.push({ busId: resolved });
+    this.buses.push({ busId });
     this.syncMixer();
     return this.buses.length - 1;
   }