@libraz/libsonare 1.7.1 → 1.8.0

package/src/worklet/engine-processor.ts

@@ -1,6 +1,8 @@
 import type { EngineClip } from '../index';
 import { RealtimeEngine } from '../index';
-import type { WorkletInput, WorkletOutput } from './audio_types';
+import { copyPlanesToOutput, type WorkletInput, type WorkletOutput } from './audio_types';
+import { emptyStripJson } from './engine-mixer-facade';
+import { requireChannelCount, requireIntegerOption } from './guards';
 import {
   DEFAULT_METRONOME_CONFIG,
   type ResolvedMetronomeConfig,
@@ -39,7 +41,6 @@ import {
   type SonareEngineTelemetryRecord,
   type SonareEngineTelemetryRingBuffer,
   SonareEngineTelemetryType,
-  type SonareWorkletMeterSnapshot,
   scopeRingFromSharedBuffer,
   telemetryFromEngine,
   writeInt64Words,
@@ -94,6 +95,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>();
@@ -112,9 +118,15 @@ export class SonareRealtimeEngineWorkletProcessor {
   ) {
     this.sampleRate = options.sampleRate ?? 48000;
     this.blockSize = options.blockSize ?? 128;
-    this.channelCount = Math.max(1, Math.floor(options.channelCount ?? 2));
+    this.channelCount = requireChannelCount(options.channelCount, 2);
     this.transport = transport;
-    this.meterIntervalFrames = Math.max(0, Math.floor(options.meterIntervalFrames ?? 2048));
+    // Zero is the off switch for meter publication, so the floor is 0.
+    this.meterIntervalFrames = requireIntegerOption(
+      options.meterIntervalFrames,
+      2048,
+      'meterIntervalFrames',
+      0,
+    );
     this.commandRing = options.commandSharedBuffer
       ? this.commandRingFromSharedBuffer(options.commandSharedBuffer, options.commandRingCapacity)
       : undefined;
@@ -146,10 +158,13 @@ export class SonareRealtimeEngineWorkletProcessor {
           options.externalMidiRingCapacity,
         )
       : undefined;
+    if (this.commandRing && this.commandRing.capacity > 65536) {
+      throw new RangeError('commandRingCapacity must be at most 65536');
+    }
     this.engine = new RealtimeEngine(
       this.sampleRate,
       this.blockSize,
-      1024,
+      Math.max(1024, this.commandRing?.capacity ?? 0),
       1024,
       this.channelCount,
     );
@@ -160,11 +175,25 @@ 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.
     if (this.scopeRing) {
-      const interval = Math.max(1, Math.floor(options.scopeIntervalFrames ?? this.blockSize));
+      // Zero is the engine's own off switch for the scope tap, so the floor is 0.
+      const interval = requireIntegerOption(
+        options.scopeIntervalFrames,
+        this.blockSize,
+        'scopeIntervalFrames',
+        0,
+      );
       this.engine.configureScopeTelemetry(interval, this.scopeRing.bands);
     }
   }
@@ -213,6 +242,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 +259,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 +289,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);
@@ -348,6 +387,14 @@ export class SonareRealtimeEngineWorkletProcessor {
         }
         break;
       }
+      case 'syncClipPagePrefetchFrames': {
+        this.engine.setClipPagePrefetchFrames(message.frames);
+        break;
+      }
+      case 'syncWarpVoiceCapacity': {
+        this.engine.setWarpVoiceCapacity(message.voices);
+        break;
+      }
       case 'syncClipPageCommit': {
         const providerId = this.pagedClipProviders.get(message.clipId);
         const clip = message.clip ?? this.pendingPagedClips.get(message.clipId);
@@ -408,11 +455,69 @@ export class SonareRealtimeEngineWorkletProcessor {
           );
         }
         break;
-      case 'syncMixer':
+      case 'syncMixer': {
+        if (message.sidechainDelta === true) {
+          // Sidechain setters send a binding delta through this message type.
+          // Their `lanes` field is context, not a request to rebuild routing;
+          // rebuilding it here would discard live insert smoother slots.
+          for (const binding of message.laneSidechains ?? []) {
+            this.engine.setLaneSidechain(
+              binding.trackId,
+              binding.insertIndex,
+              binding.sourceTrackId,
+            );
+          }
+          for (const binding of message.busSidechains ?? []) {
+            this.engine.setBusSidechain(
+              binding.busId,
+              binding.insertIndex,
+              binding.sourceKind,
+              binding.sourceId,
+            );
+          }
+          for (const binding of message.masterSidechains ?? []) {
+            this.engine.setMasterSidechain(
+              binding.insertIndex,
+              binding.sourceKind,
+              binding.sourceId,
+            );
+          }
+          break;
+        }
+        // SAB commands are published before the control thread posts this
+        // structural sync. Drain the whole snapshot so a future command past
+        // the normal 64-per-render budget cannot enter native after the strip
+        // replacement has invalidated its target.
+        if (this.commandRing) {
+          const write = Atomics.load(this.commandRing.header, 0);
+          const read = Atomics.load(this.commandRing.header, 1);
+          this.drainCommands(Math.min(this.commandRing.capacity, Math.max(0, write - read)));
+        }
+        // Complete earlier immediate edits in message order. Scheduled
+        // commands remain queued for their render frame.
+        this.engine.applyCommandsDueNowPreservingFuture();
+        this.engine.settleInsertParameters();
         if (message.buses) {
           this.engine.setTrackBuses(message.buses);
         }
         this.engine.setTrackLanes(message.lanes);
+        for (const target of message.forceInsertResets ?? []) {
+          const emptyJson = emptyStripJson(target);
+          switch (target.kind) {
+            case 'track':
+              this.engine.clearTrackInsertParameterBases(target.trackId);
+              this.engine.setTrackStripJson(target.trackId, emptyJson);
+              break;
+            case 'bus':
+              this.engine.clearBusInsertParameterBases(target.busId);
+              this.engine.setBusStripJson(target.busId, emptyJson);
+              break;
+            case 'master':
+              this.engine.clearMasterInsertParameterBases();
+              this.engine.setMasterStripJson(emptyJson);
+              break;
+          }
+        }
         for (const strip of message.trackStrips ?? []) {
           this.engine.setTrackStripJson(strip.trackId, strip.sceneJson);
         }
@@ -425,7 +530,46 @@ export class SonareRealtimeEngineWorkletProcessor {
         for (const binding of message.laneSidechains ?? []) {
           this.engine.setLaneSidechain(binding.trackId, binding.insertIndex, binding.sourceTrackId);
         }
+        for (const binding of message.busSidechains ?? []) {
+          this.engine.setBusSidechain(
+            binding.busId,
+            binding.insertIndex,
+            binding.sourceKind,
+            binding.sourceId,
+          );
+        }
+        for (const binding of message.masterSidechains ?? []) {
+          this.engine.setMasterSidechain(binding.insertIndex, binding.sourceKind, binding.sourceId);
+        }
+        for (const override of message.insertParamOverrides ?? []) {
+          switch (override.kind) {
+            case 'track':
+              this.engine.restoreTrackStripInsertParamByName(
+                override.trackId,
+                override.insertIndex,
+                override.paramName,
+                override.value,
+              );
+              break;
+            case 'bus':
+              this.engine.restoreBusStripInsertParamByName(
+                override.busId,
+                override.insertIndex,
+                override.paramName,
+                override.value,
+              );
+              break;
+            case 'master':
+              this.engine.restoreMasterStripInsertParamByName(
+                override.insertIndex,
+                override.paramName,
+                override.value,
+              );
+              break;
+          }
+        }
         break;
+      }
       case 'syncCapture':
         this.engine.setCaptureBuffer(message.channels, message.bufferFrames);
         this.engine.setCaptureSource(message.source);
@@ -438,6 +582,9 @@ export class SonareRealtimeEngineWorkletProcessor {
       case 'syncMasterStripEqBand':
         this.engine.setMasterStripEqBandJson(message.bandIndex, message.bandJson);
         break;
+      case 'syncBusStripEqBand':
+        this.engine.setBusStripEqBandJson(message.busId, message.bandIndex, message.bandJson);
+        break;
       case 'syncTrackStripInsertBypassed':
         this.engine.setTrackStripInsertBypassed(
           message.trackId,
@@ -454,26 +601,65 @@ export class SonareRealtimeEngineWorkletProcessor {
         );
         break;
       case 'syncTrackStripInsertParamByName':
-        this.engine.setTrackStripInsertParamByName(
-          message.trackId,
-          message.insertIndex,
-          message.paramName,
-          message.value,
-        );
+        this.engine.applyCommandsDueNowPreservingFuture();
+        if (
+          !this.engine.applyTrackStripInsertParamByNameNow(
+            message.trackId,
+            message.insertIndex,
+            message.paramName,
+            message.value,
+          )
+        ) {
+          // A burst can exhaust the fixed smoother slots before the next
+          // render quantum. Apply the last knob value exactly in that case.
+          this.engine.restoreTrackStripInsertParamByName(
+            message.trackId,
+            message.insertIndex,
+            message.paramName,
+            message.value,
+          );
+        }
         break;
       case 'syncMasterStripInsertParamByName':
-        this.engine.setMasterStripInsertParamByName(
-          message.insertIndex,
-          message.paramName,
-          message.value,
-        );
+        this.engine.applyCommandsDueNowPreservingFuture();
+        if (
+          !this.engine.applyMasterStripInsertParamByNameNow(
+            message.insertIndex,
+            message.paramName,
+            message.value,
+          )
+        ) {
+          this.engine.restoreMasterStripInsertParamByName(
+            message.insertIndex,
+            message.paramName,
+            message.value,
+          );
+        }
         break;
       case 'syncBusStripInsertParamByName':
-        this.engine.setBusStripInsertParamByName(
+        this.engine.applyCommandsDueNowPreservingFuture();
+        if (
+          !this.engine.applyBusStripInsertParamByNameNow(
+            message.busId,
+            message.insertIndex,
+            message.paramName,
+            message.value,
+          )
+        ) {
+          this.engine.restoreBusStripInsertParamByName(
+            message.busId,
+            message.insertIndex,
+            message.paramName,
+            message.value,
+          );
+        }
+        break;
+      case 'syncBusStripInsertBypassed':
+        this.engine.setBusStripInsertBypassed(
           message.busId,
           message.insertIndex,
-          message.paramName,
-          message.value,
+          message.bypassed,
+          message.resetOnBypass,
         );
         break;
       case 'syncTrackStripPan':
@@ -488,6 +674,18 @@ export class SonareRealtimeEngineWorkletProcessor {
       case 'syncTrackStripDualPan':
         this.engine.setTrackStripDualPan(message.trackId, message.leftPan, message.rightPan);
         break;
+      case 'syncBusStripPan':
+        this.engine.setBusStripPan(message.busId, message.pan);
+        break;
+      case 'syncBusStripPanLaw':
+        this.engine.setBusStripPanLaw(message.busId, message.panLaw);
+        break;
+      case 'syncBusStripPanMode':
+        this.engine.setBusStripPanMode(message.busId, message.panMode);
+        break;
+      case 'syncBusStripDualPan':
+        this.engine.setBusStripDualPan(message.busId, message.leftPan, message.rightPan);
+        break;
       case 'syncTrackStripChannelDelaySamples':
         this.engine.setTrackStripChannelDelaySamples(message.trackId, message.delaySamples);
         break;
@@ -539,8 +737,36 @@ export class SonareRealtimeEngineWorkletProcessor {
           message.renderFrame,
         );
         break;
+      case 'syncMidiPitchBend':
+        this.engine.pushMidiPitchBend(
+          message.destinationId,
+          message.group,
+          message.channel,
+          message.data0,
+          message.renderFrame,
+        );
+        break;
+      case 'syncMidiChannelPressure':
+        this.engine.pushMidiChannelPressure(
+          message.destinationId,
+          message.group,
+          message.channel,
+          message.data0,
+          message.renderFrame,
+        );
+        break;
+      case 'syncMidiPolyPressure':
+        this.engine.pushMidiPolyPressure(
+          message.destinationId,
+          message.group,
+          message.channel,
+          message.data0,
+          message.data1,
+          message.renderFrame,
+        );
+        break;
       case 'syncMidiUmp':
-        this.engine.pushMidiUmp(message.destinationId, message.word0, message.renderFrame);
+        this.engine.pushMidiUmp(message.destinationId, [message.word0], message.renderFrame);
         break;
       case 'syncMidiSysex':
         this.engine.pushMidiSysex(message.destinationId, message.data, message.renderFrame);
@@ -593,6 +819,31 @@ export class SonareRealtimeEngineWorkletProcessor {
           message.portTimeSamples,
         );
         break;
+      case 'syncMidiInputPitchBend':
+        this.engine.pushMidiInputPitchBend(
+          message.group,
+          message.channel,
+          message.data0,
+          message.portTimeSamples,
+        );
+        break;
+      case 'syncMidiInputChannelPressure':
+        this.engine.pushMidiInputChannelPressure(
+          message.group,
+          message.channel,
+          message.data0,
+          message.portTimeSamples,
+        );
+        break;
+      case 'syncMidiInputPolyPressure':
+        this.engine.pushMidiInputPolyPressure(
+          message.group,
+          message.channel,
+          message.data0,
+          message.data1,
+          message.portTimeSamples,
+        );
+        break;
     }
   }
 
@@ -680,11 +931,11 @@ export class SonareRealtimeEngineWorkletProcessor {
     }
   }
 
-  private drainCommands(): void {
+  private drainCommands(limit = 64): void {
     if (!this.commandRing) {
       return;
     }
-    for (let i = 0; i < 64; i++) {
+    for (let i = 0; i < limit; i++) {
       const command = popSonareEngineCommandRingBuffer(this.commandRing);
       if (!command) {
         return;
@@ -900,14 +1151,15 @@ export class SonareRealtimeEngineWorkletProcessor {
       if (meter.frame !== this.lastMeterFrame) {
         this.lastMeterFrame = meter.frame;
       }
-      // Prefer the lock-free SAB meter ring (matching the telemetry path and
-      // SonareWorkletProcessor); only fall back to structured-clone postMessage
-      // when no ring was provided, so we do not allocate/post from the audio
-      // render callback in SAB mode.
-      if (this.meterRing) {
-        this.writeMeterRing(meter);
+      // The ring branch returned above, so this is the structured-clone
+      // fallback. `onMeter` and `postMessage` are alternative channels for the
+      // same record, not a broadcast pair: the AudioWorklet registration
+      // resolves BOTH to `port.postMessage`, so calling them in turn delivered
+      // every record twice and doubled the host's peak-hold decay rate. Take
+      // the first channel the transport offers.
+      if (this.transport?.onMeter) {
+        this.transport.onMeter(meter);
       } else {
-        this.transport?.onMeter?.(meter);
         this.transport?.postMessage?.(meter);
       }
     }
@@ -926,34 +1178,18 @@ export class SonareRealtimeEngineWorkletProcessor {
     Atomics.store(ring.header, 0, writeIndex + 1);
   }
 
-  private writeMeterRing(meter: SonareWorkletMeterSnapshot): void {
-    const ring = this.meterRing;
-    if (!ring) {
-      return;
-    }
-    const writeIndex = Atomics.load(ring.header, 0);
-    const offset = (writeIndex % ring.capacity) * SONARE_METER_RING_RECORD_FLOATS;
-    ring.records[offset] = encodeFrameLo(meter.frame);
-    ring.records[offset + 1] = encodeFrameHi(meter.frame);
-    ring.records[offset + 2] = meter.targetId;
-    ring.records[offset + 3] = meter.peakDbL;
-    ring.records[offset + 4] = meter.peakDbR;
-    ring.records[offset + 5] = meter.rmsDbL;
-    ring.records[offset + 6] = meter.rmsDbR;
-    ring.records[offset + 7] = meter.correlation;
-    ring.records[offset + 8] = meter.truePeakDbL;
-    ring.records[offset + 9] = meter.truePeakDbR;
-    ring.records[offset + 10] = meter.momentaryLufs;
-    ring.records[offset + 11] = meter.shortTermLufs;
-    ring.records[offset + 12] = meter.integratedLufs;
-    ring.records[offset + 13] = meter.gainReductionDb;
-    Atomics.store(ring.header, 0, writeIndex + 1);
-    // writeIndex is a free-running monotonic counter, so an overflow guard here
-    // would fire on essentially every write past the first `capacity` records
-    // and store an ever-growing value, not a dropped-record count. Readers
-    // already detect silent overrun via firstReadable = max(readIndex,
-    // writeIndex - capacity), so header slot 3 is left at its initial 0.
-  }
+  // A snapshot-object ring writer used to live here as well. It was
+  // unreachable: publishMeters returns after the writeMeterScratch loop
+  // whenever a ring exists, so the ring is never fed from a materialised
+  // snapshot. writeMeterScratch above is the only ring writer, and it keeps the
+  // render callback allocation-free by reading the engine's scratch registers
+  // directly.
+  //
+  // writeIndex is a free-running monotonic counter, so an overflow guard would
+  // fire on essentially every write past the first `capacity` records and store
+  // an ever-growing value, not a dropped-record count. Readers already detect
+  // silent overrun via firstReadable = max(readIndex, writeIndex - capacity),
+  // so header slot 3 is left at its initial 0.
 
   // Drains the engine's scope producer (FFT spectrum + goniometer points) into
   // the lock-free SAB scope ring. No allocation on the render path: records are

package/src/worklet/engine-register.ts

@@ -9,6 +9,7 @@ import {
   isEngineTransportRequestMessage,
 } from './guards';
 import type { SonareRealtimeEngineWorkletProcessorOptions, WorkletPort } from './messages';
+import { isRecord } from './protocol';
 
 export function registerSonareRealtimeEngineWorkletProcessor(
   name = 'sonare-realtime-engine-processor',
@@ -43,15 +44,7 @@ export function registerSonareRealtimeEngineWorkletProcessor(
           }
           return;
         }
-        if (isEngineCommandRecord(event.data)) {
-          this.bridge.receiveCommand(event.data);
-        } else if (isEngineSyncMessage(event.data)) {
-          this.bridge.receiveSync(event.data);
-        } else if (isEngineCaptureRequestMessage(event.data)) {
-          this.bridge.receiveCaptureRequest(event.data);
-        } else if (isEngineTransportRequestMessage(event.data)) {
-          this.bridge.receiveTransportRequest(event.data);
-        }
+        this.routeMessage(event.data);
       };
       if (port?.addEventListener) {
         port.addEventListener('message', onMessage);
@@ -72,18 +65,39 @@ export function registerSonareRealtimeEngineWorkletProcessor(
       return true;
     }
 
+    /**
+     * Single dispatch point for the port, shared with the buffered replay so
+     * the two cannot recognize different message sets.
+     */
+    private routeMessage(data: unknown): void {
+      const bridge = this.bridge;
+      if (!bridge) {
+        return;
+      }
+      if (isEngineCommandRecord(data)) {
+        bridge.receiveCommand(data);
+      } else if (isEngineSyncMessage(data)) {
+        bridge.receiveSync(data);
+      } else if (isEngineCaptureRequestMessage(data)) {
+        bridge.receiveCaptureRequest(data);
+      } else if (isEngineTransportRequestMessage(data)) {
+        bridge.receiveTransportRequest(data);
+      } else if (isRecord(data) && typeof data.type === 'string' && data.type.startsWith('sync')) {
+        // A sync the guard does not accept would otherwise vanish, leaving the
+        // live engine out of step with the offline mirror and nothing to see.
+        // Report it through the same channel as a sync the engine rejected.
+        this.port?.postMessage?.({
+          type: 'syncError',
+          syncType: data.type,
+          message: `Unrecognized worklet sync message: ${data.type}`,
+        });
+      }
+    }
+
     private replayPendingMessages(): void {
       const messages = this.pendingMessages.splice(0);
       for (const data of messages) {
-        if (isEngineCommandRecord(data)) {
-          this.bridge?.receiveCommand(data);
-        } else if (isEngineSyncMessage(data)) {
-          this.bridge?.receiveSync(data);
-        } else if (isEngineCaptureRequestMessage(data)) {
-          this.bridge?.receiveCaptureRequest(data);
-        } else if (isEngineTransportRequestMessage(data)) {
-          this.bridge?.receiveTransportRequest(data);
-        }
+        this.routeMessage(data);
       }
     }