@libraz/libsonare 1.5.5 → 1.7.0

package/src/worklet/engine.ts

@@ -1,3 +1,8 @@
+import {
+  ClipPageStreamer,
+  type ClipPageStreamerRequest,
+  type OpfsClipStreamOptions,
+} from '../clip_page_streamer';
 import type {
   EngineAutomationPoint,
   EngineBus,
@@ -10,13 +15,17 @@ import type {
   EngineTempoSegment,
   EngineTimeSignatureSegment,
   EngineTrackLane,
+  EngineTrackMonitorMode,
   EngineTrackSend,
   EngineTransportState,
   EqBand,
+  MidiCcBindOptions,
   PanLaw,
   PanMode,
 } from '../index';
 import { RealtimeEngine } from '../index';
+import { createOpfsClipPageProvider, type OpfsClipPageProviderBinding } from '../opfs_clip_pages';
+import type { ClipPageProvider } from '../realtime_engine';
 import type { EngineAutomationContext } from './engine-automation';
 import * as automation from './engine-automation';
 import type { EngineCaptureContext } from './engine-capture-facade';
@@ -56,6 +65,24 @@ import {
   type SonareWorkletScopeSnapshot,
 } from './protocol';
 
+const MAX_PENDING_WORKLET_CLIP_PAGE_REQUESTS = 256;
+
+function transferableAudioBuffers(channels: readonly Float32Array[]): Transferable[] {
+  const transfers: ArrayBuffer[] = [];
+  const seen = new Set<ArrayBuffer>();
+  for (const channel of channels) {
+    const buffer = channel.buffer;
+    // SharedArrayBuffer is cloneable but cannot appear in a transfer list. A
+    // worker may intentionally return SAB-backed pages, so transfer only plain,
+    // distinct ArrayBuffers and let structured clone share SABs by reference.
+    if (buffer instanceof ArrayBuffer && !seen.has(buffer)) {
+      seen.add(buffer);
+      transfers.push(buffer);
+    }
+  }
+  return transfers;
+}
+
 export class SonareEngine {
   readonly node: AudioWorkletNode;
   readonly capabilities: SonareRealtimeEngineNodeCapabilities;
@@ -93,6 +120,15 @@ export class SonareEngine {
   private nextMarkerId = 1;
   private transportPlaying = false;
   private readonly pendingInstrumentSync: SonareEngineInstrumentSyncMessage[] = [];
+  // One latest frontier per clip is sufficient: ClipPageStreamer expands it to
+  // the bounded read window. A Map both coalesces repeated page misses and
+  // places a hard cap on work queued while OPFS I/O is stalled.
+  private readonly workletClipPageRequests = new Map<number, ClipPageStreamerRequest>();
+  private readonly workletPageProviderClipIds = new Map<number, number>();
+  private workletClipStreamer: ClipPageStreamer | undefined;
+  private workletClipPump: Promise<void> | undefined;
+  private workletClipPagePollTimer: ReturnType<typeof setInterval> | undefined;
+  private unsubscribeWorkletClipRequests: (() => void) | undefined;
   private destroyed = false;
 
   private constructor(
@@ -111,10 +147,17 @@ export class SonareEngine {
     this.sampleRate = sampleRate;
     this.offlineBlockSize = offlineBlockSize;
     this.offlineChannelCount = offlineChannelCount;
+    this.unsubscribeWorkletClipRequests = this.realtimeNode.onClipPageRequests((message) => {
+      for (const request of message.requests) {
+        this.enqueueWorkletClipPageRequest(request);
+      }
+      this.pumpWorkletClipPages();
+    });
     this.transport = buildTransportFacade({
       sampleRate: this.sampleRate,
       realtimeNode: this.realtimeNode,
       offlineEngine: this.offlineEngine,
+      flushOfflineMirror: () => this.flushOfflineMirror(),
       setTransportPlaying: (playing) => {
         this.transportPlaying = playing;
       },
@@ -136,8 +179,17 @@ export class SonareEngine {
       Math.floor(options.offlineChannelCount ?? options.channelCount ?? 2),
     );
     const realtimeNode = await SonareRealtimeEngineNode.create(context, options);
+    try {
+      // Do not expose the facade while the registered processor is still
+      // buffering messages. Long clip sync must either begin after the bridge
+      // is ready or fail explicitly; it may never be silently truncated.
+      await realtimeNode.ready;
+    } catch (error) {
+      realtimeNode.destroy();
+      throw error;
+    }
     const offlineEngine = options.offlineEngine ?? new RealtimeEngine(sampleRate, blockSize);
-    return new SonareEngine(
+    const engine = new SonareEngine(
       context,
       realtimeNode,
       offlineEngine,
@@ -145,6 +197,8 @@ export class SonareEngine {
       blockSize,
       channelCount,
     );
+    engine.syncParameters();
+    return engine;
   }
 
   async suspend(): Promise<void> {
@@ -319,10 +373,29 @@ export class SonareEngine {
     return parameter.listParameters(this.parameterContext);
   }
 
+  /** Registers a custom parameter on the offline mirror and worklet engine. */
+  addParameter(info: EngineParameterInfo): void {
+    parameter.addParameter(this.parameterContext, info);
+  }
+
+  /** Clears custom parameters and their automation lanes on both engines. */
+  clearParameters(): void {
+    parameter.clearParameters(this.parameterContext);
+  }
+
   setSoloMute(target: string | number, solo: boolean, mute: boolean): boolean {
     return parameter.setSoloMute(this.parameterContext, target, solo, mute);
   }
 
+  /** Queues a per-track PFL/AFL monitor tap mode change. */
+  setTrackMonitorMode(
+    target: string | number,
+    mode: EngineTrackMonitorMode,
+    renderFrame = -1,
+  ): boolean {
+    return parameter.setTrackMonitorMode(this.parameterContext, target, mode, renderFrame);
+  }
+
   setStripGain(target: string | number, db: number): boolean {
     return this.sendSmoothedParam(this.stripParamId(target, ENGINE_MIXER_PARAM_FADER_DB), db);
   }
@@ -516,11 +589,86 @@ export class SonareEngine {
     this.setMasterStripJson(sceneJson);
   }
 
+  /**
+   * Creates and primes an OPFS-backed page provider for this live worklet
+   * engine. Pass the returned `provider` to {@link addClip} in place of a
+   * `Float32Array[]`; the `clipId` in `options` must equal that clip's explicit
+   * `opts.id`. Subsequent cache misses are fetched on the main thread and
+   * supplied back to the worklet through its bounded pull protocol.
+   */
+  async attachOpfsClipStream(
+    options: OpfsClipStreamOptions,
+  ): Promise<{ binding: OpfsClipPageProviderBinding; provider: ClipPageProvider }> {
+    if (this.destroyed) {
+      throw new Error('SonareEngine is destroyed.');
+    }
+    if (!this.capabilities.clipPageRequestsRealtimeSafe) {
+      throw new Error(
+        'OPFS clip streaming requires SharedArrayBuffer clip-page requests; the postMessage fallback is not realtime-safe.',
+      );
+    }
+    const { clipId, primePages = 1, ...providerOptions } = options;
+    if ([...this.workletPageProviderClipIds.values()].includes(clipId)) {
+      throw new Error(`An OPFS stream is already attached for clip ${clipId}.`);
+    }
+    const streamer = this.ensureWorkletClipStreamer();
+    // Allocate the worklet-owned provider before priming: port message order
+    // ensures every prime page is adopted before addClip commits its schedule.
+    this.postSync({
+      type: 'syncClipPageProvider',
+      clipId,
+      numChannels: providerOptions.numChannels,
+      numSamples: providerOptions.numSamples,
+      pageFrames: providerOptions.pageFrames,
+    });
+    let binding: OpfsClipPageProviderBinding;
+    binding = createOpfsClipPageProvider(this.offlineEngine, {
+      ...providerOptions,
+      onPageSupplied: (pageIndex, channels) => {
+        this.postSync(
+          { type: 'syncClipPage', clipId, pageIndex, channels },
+          transferableAudioBuffers(channels),
+        );
+      },
+      onPageCleared: (pageIndex) => {
+        this.postSync({ type: 'syncClipPageClear', clipId, pageIndex });
+      },
+      onClose: () => {
+        this.workletPageProviderClipIds.delete(binding.provider.id);
+        this.postSync({ type: 'syncClipPageDestroy', clipId });
+      },
+    });
+    this.workletPageProviderClipIds.set(binding.provider.id, clipId);
+    const lastPage = Math.ceil(providerOptions.numSamples / providerOptions.pageFrames) - 1;
+    const primed: number[] = [];
+    try {
+      for (let page = 0; page < primePages && page <= lastPage; ++page) {
+        if (await binding.supplyPage(page)) {
+          primed.push(page);
+        }
+      }
+      streamer.addSource(
+        {
+          clipId,
+          binding,
+          pageFrames: providerOptions.pageFrames,
+          numSamples: providerOptions.numSamples,
+        },
+        primed,
+      );
+      this.startWorkletClipPagePolling();
+    } catch (error) {
+      binding.close();
+      throw error;
+    }
+    return { binding, provider: binding.provider };
+  }
+
   addClip(
     trackId: string | number,
-    buffer: Float32Array[],
+    buffer: Float32Array[] | ClipPageProvider,
     startPpq: number,
-    opts: Partial<Omit<EngineClip, 'channels' | 'startPpq'>> = {},
+    opts: Partial<Omit<EngineClip, 'channels' | 'pageProvider' | 'startPpq'>> = {},
   ): number {
     return clips.addClip(this.clipContext, trackId, buffer, startPpq, opts);
   }
@@ -550,7 +698,12 @@ export class SonareEngine {
 
   setSf2Instrument(
     trackId: string | number,
-    config: { destinationId?: number; gain?: number; polyphony?: number } = {},
+    config: {
+      destinationId?: number;
+      gain?: number;
+      polyphony?: number;
+      preferModelForModeledFamilies?: boolean;
+    } = {},
   ): void {
     strips.setSf2Instrument(this.stripContext, trackId, config);
   }
@@ -623,10 +776,90 @@ export class SonareEngine {
     strips.pushMidiCc(this.stripContext, trackId, group, channel, controller, value, renderFrame);
   }
 
+  pushMidiUmp(trackId: string | number, word0: number, renderFrame = -1): void {
+    strips.pushMidiUmp(this.stripContext, trackId, word0, renderFrame);
+  }
+
   pushMidiSysex(trackId: string | number, data: Uint8Array, renderFrame = -1): void {
     strips.pushMidiSysex(this.stripContext, trackId, data, renderFrame);
   }
 
+  bindMidiCc(
+    channel: number,
+    controller: number,
+    paramId: number,
+    options: MidiCcBindOptions = {},
+  ): void {
+    const minValue = options.minValue ?? 0;
+    const maxValue = options.maxValue ?? 1;
+    this.offlineEngine.bindMidiCc(channel, controller, paramId, { minValue, maxValue });
+    this.postSync({ type: 'syncMidiCcBinding', channel, controller, paramId, minValue, maxValue });
+  }
+
+  setMidiInputSource(destinationId = 0): void {
+    this.offlineEngine.setMidiInputSource(destinationId);
+    this.postSync({ type: 'syncMidiInputSource', destinationId });
+  }
+
+  clearMidiInputSource(): void {
+    this.offlineEngine.clearMidiInputSource();
+    this.postSync({ type: 'syncClearMidiInputSource' });
+  }
+
+  pushMidiInputNoteOn(
+    group: number,
+    channel: number,
+    note: number,
+    velocity: number,
+    portTimeSamples = 0,
+  ): void {
+    this.offlineEngine.pushMidiInputNoteOn(group, channel, note, velocity, portTimeSamples);
+    this.postSync({
+      type: 'syncMidiInputNoteOn',
+      group,
+      channel,
+      data0: note,
+      data1: velocity,
+      portTimeSamples,
+    });
+  }
+
+  pushMidiInputNoteOff(
+    group: number,
+    channel: number,
+    note: number,
+    velocity = 0,
+    portTimeSamples = 0,
+  ): void {
+    this.offlineEngine.pushMidiInputNoteOff(group, channel, note, velocity, portTimeSamples);
+    this.postSync({
+      type: 'syncMidiInputNoteOff',
+      group,
+      channel,
+      data0: note,
+      data1: velocity,
+      portTimeSamples,
+    });
+  }
+
+  pushMidiInputCc(
+    group: number,
+    channel: number,
+    controller: number,
+    value: number,
+    portTimeSamples = 0,
+  ): void {
+    this.offlineEngine.pushMidiInputCc(group, channel, controller, value, portTimeSamples);
+    this.postSync({
+      type: 'syncMidiInputCc',
+      group,
+      channel,
+      data0: controller,
+      data1: value,
+      portTimeSamples,
+    });
+  }
+
   pushMidiPanic(renderFrame = -1): void {
     this.offlineEngine.pushMidiPanic(renderFrame);
     this.postSync({ type: 'syncMidiPanic', renderFrame });
@@ -636,6 +869,10 @@ export class SonareEngine {
     capture.configureCapture(this.captureContext, options);
   }
 
+  /**
+   * Arms the engine-global capture path. `trackId` is retained for source
+   * compatibility and must be `0`; per-track capture is not implemented.
+   */
   armRecord(trackId: string | number, enabled: boolean): boolean {
     return capture.armRecord(this.captureContext, trackId, enabled);
   }
@@ -662,7 +899,7 @@ export class SonareEngine {
     // the fixed-size SAB command record, so it is delivered out-of-band; the
     // SetMetronome command then toggles enabled state on the audio thread.
     this.postSync({ type: 'syncMetronome', config: opts });
-    this.realtimeNode.sendCommand({
+    this.sendMirroredCommand({
       type: SonareEngineCommandType.SetMetronome,
       sampleTime: -1,
       argInt: opts.enabled ? 1 : 0,
@@ -748,6 +985,15 @@ export class SonareEngine {
     if (this.destroyed) {
       return;
     }
+    this.unsubscribeWorkletClipRequests?.();
+    this.unsubscribeWorkletClipRequests = undefined;
+    this.workletClipStreamer?.close();
+    this.workletClipStreamer = undefined;
+    if (this.workletClipPagePollTimer !== undefined) {
+      clearInterval(this.workletClipPagePollTimer);
+      this.workletClipPagePollTimer = undefined;
+    }
+    this.workletClipPageRequests.clear();
     this.destroyed = true;
     this.transport.stop();
     this.realtimeNode.pollTelemetry();
@@ -755,6 +1001,107 @@ export class SonareEngine {
     this.offlineEngine.destroy();
   }
 
+  private ensureWorkletClipStreamer(): ClipPageStreamer {
+    if (!this.workletClipStreamer) {
+      this.workletClipStreamer = new ClipPageStreamer({
+        popClipPageRequest: () => this.popWorkletClipPageRequest(),
+      });
+    }
+    return this.workletClipStreamer;
+  }
+
+  /**
+   * SAB requests have no postMessage wake-up by design. Polling on the main
+   * thread is therefore intentionally outside the audio callback; 8 ms keeps
+   * the bounded OPFS prefetch frontier responsive without adding worklet GC.
+   */
+  private startWorkletClipPagePolling(): void {
+    if (this.workletClipPagePollTimer !== undefined) {
+      return;
+    }
+    const poll = () => {
+      if (!this.destroyed) {
+        this.realtimeNode.pollClipPageRequests();
+      }
+    };
+    poll();
+    this.workletClipPagePollTimer = setInterval(poll, 8);
+  }
+
+  private pumpWorkletClipPages(): void {
+    const streamer = this.workletClipStreamer;
+    if (!streamer || this.workletClipPump) {
+      return;
+    }
+    this.workletClipPump = streamer
+      .pump()
+      .catch((error: unknown) => {
+        // The worklet keeps rendering silence for an unavailable page. Surface
+        // I/O failures without converting them into an AudioWorklet exception.
+        // biome-ignore lint/suspicious/noConsole: asynchronous OPFS diagnostic.
+        console.error('Sonare OPFS clip-page supply failed:', error);
+      })
+      .finally(() => {
+        this.workletClipPump = undefined;
+        if (this.workletClipPageRequests.size > 0) {
+          this.pumpWorkletClipPages();
+        }
+      });
+  }
+
+  private enqueueWorkletClipPageRequest(request: ClipPageStreamerRequest): void {
+    if (
+      !Number.isInteger(request.clipId) ||
+      request.clipId < 0 ||
+      !Number.isInteger(request.pageIndex) ||
+      (request.pageIndex ?? -1) < 0
+    ) {
+      return;
+    }
+    // Reinsert an existing id so iteration order represents newest frontiers.
+    this.workletClipPageRequests.delete(request.clipId);
+    if (this.workletClipPageRequests.size >= MAX_PENDING_WORKLET_CLIP_PAGE_REQUESTS) {
+      const oldest = this.workletClipPageRequests.keys().next().value;
+      if (oldest !== undefined) {
+        this.workletClipPageRequests.delete(oldest);
+      }
+    }
+    this.workletClipPageRequests.set(request.clipId, request);
+  }
+
+  private popWorkletClipPageRequest(): ClipPageStreamerRequest | null {
+    const entry = this.workletClipPageRequests.entries().next().value;
+    if (!entry) {
+      return null;
+    }
+    const [clipId, request] = entry;
+    this.workletClipPageRequests.delete(clipId);
+    return request;
+  }
+
+  private commitWorkletClipPageProvider(clip: EngineClip): boolean {
+    const providerId =
+      typeof clip.pageProvider === 'object' && clip.pageProvider !== null
+        ? clip.pageProvider.id
+        : clip.pageProvider;
+    if (providerId === undefined) {
+      return false;
+    }
+    const clipId = this.workletPageProviderClipIds.get(providerId);
+    if (clipId === undefined) {
+      return false;
+    }
+    if (clip.id !== clipId) {
+      throw new Error(`OPFS stream clipId ${clipId} must match addClip(..., { id: ${clipId} }).`);
+    }
+    this.postSync({
+      type: 'syncClipPageCommit',
+      clipId,
+      clip: { ...clip, channels: undefined, pageProvider: undefined },
+    });
+    return true;
+  }
+
   private mixerLanes(): EngineTrackLane[] {
     return mixer.mixerLanes(this.mixerContext);
   }
@@ -791,13 +1138,32 @@ export class SonareEngine {
     if (this.destroyed) {
       return;
     }
-    if (transfer && transfer.length > 0) {
-      this.realtimeNode.node.port.postMessage(message, transfer);
-    } else {
-      this.realtimeNode.node.port.postMessage(message);
+    try {
+      if (transfer && transfer.length > 0) {
+        this.realtimeNode.node.port.postMessage(message, transfer);
+      } else {
+        this.realtimeNode.node.port.postMessage(message);
+      }
+    } finally {
+      this.flushOfflineMirror();
     }
   }
 
+  // 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.
+  private flushOfflineMirror(): void {
+    this.offlineEngine.flushControlCommands();
+  }
+
+  private sendMirroredCommand(
+    command: Parameters<SonareRealtimeEngineNode['sendCommand']>[0],
+  ): boolean {
+    const accepted = this.realtimeNode.sendCommand(command);
+    this.flushOfflineMirror();
+    return accepted;
+  }
+
   // Collaborator surface handed to the mixer/routing free functions so they can
   // mutate the routing stores (held by reference), mirror into the offline
   // engine, post mixer-sync messages, and declare lanes/buses without a
@@ -855,13 +1221,13 @@ export class SonareEngine {
     return {
       offlineEngine: this.offlineEngine,
       realtimeNode: this.realtimeNode,
+      sendCommand: (command) => this.sendMirroredCommand(command),
       offlineChannelCount: this.offlineChannelCount,
       postSync: (message) => this.postSync(message),
       getCaptureConfig: () => this.captureConfig,
       setCaptureConfig: (config) => {
         this.captureConfig = config;
       },
-      resolveTargetId: (target) => this.resolveTargetId(target),
     };
   }
 
@@ -872,7 +1238,9 @@ export class SonareEngine {
   private get parameterContext(): EngineParameterContext {
     return {
       offlineEngine: this.offlineEngine,
-      realtimeNode: this.realtimeNode,
+      sendCommand: (command) => this.sendMirroredCommand(command),
+      postSync: (message) => this.postSync(message),
+      automationLanes: this.automationLanes,
       trackLaneIds: this.trackLaneIds,
       resolveParamId: (nodeId, param) => this.resolveParamId(nodeId, param),
       ensureTrackLane: (target) => this.ensureTrackLane(target),
@@ -887,6 +1255,7 @@ export class SonareEngine {
     return {
       offlineEngine: this.offlineEngine,
       realtimeNode: this.realtimeNode,
+      sendCommand: (command) => this.sendMirroredCommand(command),
       postSync: (message) => this.postSync(message),
       getTempoBpm: () => this.tempoBpm,
       setTempoBpm: (bpm) => {
@@ -923,6 +1292,7 @@ export class SonareEngine {
       postSync: (message, transfer) => this.postSync(message, transfer),
       ensureTrackLane: (target) => this.ensureTrackLane(target),
       resolveTargetId: (target) => this.resolveTargetId(target),
+      commitWorkletClipPageProvider: (clip) => this.commitWorkletClipPageProvider(clip),
     };
   }
 
@@ -938,7 +1308,7 @@ export class SonareEngine {
         this.nextMarkerId = value;
       },
       postSync: (message) => this.postSync(message),
-      sendCommand: (command) => this.realtimeNode.sendCommand(command),
+      sendCommand: (command) => this.sendMirroredCommand(command),
       setLoop: (startPpq, endPpq, enabled) => this.setLoop(startPpq, endPpq, enabled),
     };
   }
@@ -956,7 +1326,7 @@ export class SonareEngine {
   // sample-accurate smoothed-param command to the realtime runtime.
   private sendSmoothedParam(paramId: number, value: number): boolean {
     this.offlineEngine.setParameter(paramId, value);
-    return this.realtimeNode.sendCommand({
+    return this.sendMirroredCommand({
       type: SonareEngineCommandType.SetParamSmoothed,
       targetId: paramId,
       sampleTime: -1,
@@ -968,6 +1338,13 @@ export class SonareEngine {
     return resolveParamId(this.listParameters(), nodeId, param);
   }
 
+  private syncParameters(): void {
+    const parameters = this.listParameters();
+    if (parameters.length > 0) {
+      this.postSync({ type: 'syncParameters', parameters });
+    }
+  }
+
   private resolveTargetId(target: string | number): number {
     return resolveTargetId(target);
   }