@libraz/libsonare 1.7.0 → 1.7.2

package/src/worklet/engine-node.ts

@@ -301,10 +301,12 @@ export class SonareRealtimeEngineNode {
         ? createSonareExternalMidiRingBuffer(options.externalMidiRingCapacity ?? 256)
         : undefined;
     const channelCount = Math.max(1, Math.floor(options.channelCount ?? 2));
+    const cueOutput = options.cueOutput === true;
     const processorOptions: SonareRealtimeEngineWorkletProcessorOptions = {
       sampleRate: options.sampleRate ?? context.sampleRate,
       blockSize,
       channelCount,
+      cueOutput,
       commandSharedBuffer: commandRing?.sharedBuffer,
       commandRingCapacity: commandRing?.capacity,
       telemetrySharedBuffer: telemetryRing?.sharedBuffer,
@@ -329,8 +331,10 @@ export class SonareRealtimeEngineNode {
         new AudioWorkletNode(ctx, name, nodeOptions));
     const node = factory(context, processorName, {
       numberOfInputs: 1,
-      numberOfOutputs: 1,
-      outputChannelCount: [channelCount],
+      // The cue bus needs its own output; a single-output node keeps the
+      // historical mix where process() folds the cue into the program.
+      numberOfOutputs: cueOutput ? 2 : 1,
+      outputChannelCount: cueOutput ? [channelCount, channelCount] : [channelCount],
       processorOptions,
     });
     return new SonareRealtimeEngineNode(
@@ -343,6 +347,7 @@ export class SonareRealtimeEngineNode {
         audioWorklet,
         clipPageRequestsRealtimeSafe: mode === 'sab',
         externalMidiRealtimeSafe: mode === 'sab',
+        cueOutput,
         engineAbiVersion: detectedCapabilities?.engineAbiVersion,
         expectedEngineAbiVersion: detectedCapabilities?.expectedEngineAbiVersion,
         abiCompatible: detectedCapabilities?.abiCompatible,

package/src/worklet/engine-processor.ts

@@ -46,6 +46,30 @@ import {
   writeSonareEngineTelemetryRingBuffer,
 } from './protocol';
 
+/**
+ * Copies one plane per output channel, zero-filling the tail past `frames` and
+ * any channel the source does not cover. Shared by the program and cue outputs
+ * so the two cannot drift in their padding behaviour. Allocation-free.
+ */
+function copyPlanesToOutput(
+  output: Float32Array[],
+  planes: readonly Float32Array[],
+  frames: number,
+): void {
+  for (let ch = 0; ch < output.length; ch++) {
+    const target = output[ch];
+    const source = planes[ch] ?? planes[0];
+    if (source) {
+      target.set(source.subarray(0, Math.min(target.length, frames)));
+      if (target.length > frames) {
+        target.fill(0, frames);
+      }
+    } else {
+      target.fill(0);
+    }
+  }
+}
+
 function captureTransferList(channels: readonly Float32Array[]): Transferable[] {
   const transfers: ArrayBuffer[] = [];
   const seen = new Set<ArrayBuffer>();
@@ -94,6 +118,11 @@ export class SonareRealtimeEngineWorkletProcessor {
   // allocated per render quantum (the old engine.process() round-tripped fresh
   // arrays on both heaps every block, an RT-safety hazard).
   private channelBuffers: Float32Array[];
+  // Cue-bus plane, allocated only when the host asked for a separate PFL/AFL
+  // output. Empty otherwise, so a single-output host pays no heap and keeps the
+  // historical behaviour where process() folds the cue into the program mix.
+  private monitorBuffers: Float32Array[] = [];
+  private readonly cueOutput: boolean;
   private readonly liveClips = new Map<number, EngineClip>();
   private readonly pagedClipProviders = new Map<number, number>();
   private readonly pagedClipPageFrames = new Map<number, number>();
@@ -160,6 +189,14 @@ export class SonareRealtimeEngineWorkletProcessor {
     for (let ch = 0; ch < this.channelCount; ch++) {
       this.channelBuffers[ch] = this.engine.getChannelBuffer(ch, this.blockSize);
     }
+    this.cueOutput = options.cueOutput === true;
+    if (this.cueOutput) {
+      this.engine.prepareMonitorChannels(this.channelCount, this.blockSize);
+      this.monitorBuffers = new Array(this.channelCount);
+      for (let ch = 0; ch < this.channelCount; ch++) {
+        this.monitorBuffers[ch] = this.engine.getMonitorChannelBuffer(ch, this.blockSize);
+      }
+    }
     // Arm the engine's scope producer only when a scope ring was provided. The
     // band count follows the ring's record layout so writeScopeRing never
     // overruns its slot.
@@ -213,6 +250,9 @@ export class SonareRealtimeEngineWorkletProcessor {
     if ((this.channelBuffers[0]?.byteLength ?? 0) === 0) {
       this.reacquireChannelBuffers();
     }
+    if (this.cueOutput && (this.monitorBuffers[0]?.byteLength ?? 0) === 0) {
+      this.reacquireMonitorBuffers();
+    }
 
     const input = inputs[0];
     // Write the AudioWorklet input straight into the engine's WASM-heap views;
@@ -227,19 +267,20 @@ export class SonareRealtimeEngineWorkletProcessor {
       }
     }
 
-    // Run the engine in place over the prepared scratch (allocation-free).
-    this.engine.processPrepared(usableFrames);
+    // Run the engine in place over the prepared scratch (allocation-free). The
+    // monitor variant keeps the cue bus out of the program planes so it can go
+    // to its own output; the plain call folds it in, as it always has.
+    if (this.cueOutput) {
+      this.engine.processPreparedWithMonitor(usableFrames);
+    } else {
+      this.engine.processPrepared(usableFrames);
+    }
 
-    for (let ch = 0; ch < output.length; ch++) {
-      const target = output[ch];
-      const source = this.channelBuffers[ch] ?? this.channelBuffers[0];
-      if (source) {
-        target.set(source.subarray(0, Math.min(target.length, usableFrames)));
-        if (target.length > usableFrames) {
-          target.fill(0, usableFrames);
-        }
-      } else {
-        target.fill(0);
+    copyPlanesToOutput(output, this.channelBuffers, usableFrames);
+    if (this.cueOutput) {
+      const cue = outputs[1];
+      if (cue) {
+        copyPlanesToOutput(cue, this.monitorBuffers, usableFrames);
       }
     }
     this.publishClipPageRequests();
@@ -256,6 +297,12 @@ export class SonareRealtimeEngineWorkletProcessor {
     }
   }
 
+  private reacquireMonitorBuffers(): void {
+    for (let ch = 0; ch < this.channelCount; ch++) {
+      this.monitorBuffers[ch] = this.engine.getMonitorChannelBuffer(ch, this.blockSize);
+    }
+  }
+
   receiveCommand(command: SonareEngineCommandRecord): void {
     if (!this.closed) {
       this.safeApplyCommand(command);

package/src/worklet/messages.ts

@@ -67,6 +67,13 @@ export interface SonareRealtimeEngineWorkletProcessorOptions {
   /** Lock-free worklet-to-main-thread MIDI-1 output ring. */
   externalMidiSharedBuffer?: SharedArrayBuffer;
   externalMidiRingCapacity?: number;
+  /**
+   * Route the PFL/AFL cue bus to the processor's SECOND output instead of
+   * folding it into the program output. Off by default, so an existing
+   * single-output host keeps its current mix sample for sample. The node must
+   * be constructed with two outputs for the cue to be audible.
+   */
+  cueOutput?: boolean;
 }
 
 export interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
@@ -105,6 +112,11 @@ export interface SonareRealtimeEngineNodeCapabilities {
   clipPageRequestsRealtimeSafe: boolean;
   /** True when external MIDI uses the SAB output ring rather than postMessage. */
   externalMidiRealtimeSafe: boolean;
+  /**
+   * True when the node carries a second output fed by the PFL/AFL cue bus. When
+   * false the cue is folded into the program output, as it always was.
+   */
+  cueOutput: boolean;
   engineAbiVersion?: number;
   expectedEngineAbiVersion?: number;
   abiCompatible?: boolean;

package/src/worklet.ts

@@ -10,6 +10,11 @@ export { attachOpfsClipStream } from './clip_page_streamer';
 // module singleton. Re-export the lifecycle so that realm can initialize its
 // own wasm instance, independent of the main-thread `index` module.
 export { init, isInitialized } from './index';
+// Host-side mastering preview inside the worklet realm. Kept here rather than
+// left main-thread-only so a live preview does not have to round-trip audio to
+// the main thread; see the class doc for the prepare/loudness/latency contract.
+export type { StreamingMasteringChainConfig } from './public_types';
+export { StreamingMasteringChain } from './streaming_processors';
 export { SonareEngine } from './worklet/engine';
 export { SonareRealtimeEngineNode } from './worklet/engine-node';
 export type { SonareEngineOptions } from './worklet/engine-options';