@libraz/libsonare 1.7.1 → 1.8.0

package/src/worklet/engine-node.ts

@@ -9,6 +9,8 @@ import {
   isEngineTransportResponseMessage,
   isExternalMidiBatchMessage,
   isMeterSnapshot,
+  requireChannelCount,
+  requireIntegerOption,
 } from './guards';
 import type {
   SonareEngineCaptureRequestMessage,
@@ -29,6 +31,7 @@ import {
   createSonareMeterRingBuffer,
   createSonareScopeRingBuffer,
   isRecord,
+  isUint32Slot,
   pushSonareEngineCommandRingBuffer,
   readSonareClipPageRequestRingBuffer,
   readSonareEngineTelemetryRingBuffer,
@@ -63,13 +66,6 @@ function isTrackMonitorMode(value: number | bigint | undefined): boolean {
   return typeof mode === 'number' && Number.isSafeInteger(mode) && mode >= 0 && mode <= 2;
 }
 
-/** A track-monitor command cannot infer a lane: its target is a uint32 index. */
-function isTrackMonitorLaneIndex(value: number | undefined): boolean {
-  return (
-    typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= 0xffff_ffff
-  );
-}
-
 function isValidCommandRecord(command: SonareEngineCommandRecord): boolean {
   const type = Number(command.type);
   if (
@@ -81,12 +77,15 @@ function isValidCommandRecord(command: SonareEngineCommandRecord): boolean {
     return false;
   }
   return (
-    (command.targetId === undefined || Number.isSafeInteger(command.targetId)) &&
+    // The record writer refuses a targetId outside the slot by throwing, and
+    // this path answers false instead, so it must reject the same domain here.
+    (command.targetId === undefined || isUint32Slot(command.targetId)) &&
     (command.argFloat === undefined || Number.isFinite(command.argFloat)) &&
     isFiniteInteger(command.argInt) &&
     isFiniteInteger(command.sampleTime) &&
+    // A track-monitor command cannot infer a lane: its target is required.
     (type !== SonareEngineCommandType.SetTrackMonitorMode ||
-      (isTrackMonitorLaneIndex(command.targetId) && isTrackMonitorMode(command.argInt)))
+      (isUint32Slot(command.targetId) && isTrackMonitorMode(command.argInt)))
   );
 }
 
@@ -172,6 +171,12 @@ export class SonareRealtimeEngineNode {
       this.resolveReady();
     }
     this.node.port.onmessage = (event: MessageEvent<unknown>) => {
+      // A host that kept its own reference to this handler (or a port
+      // implementation that ignores the detach in destroy()) must not be able
+      // to reach listeners of a node the host already disposed.
+      if (this.destroyed) {
+        return;
+      }
       const captureRequestId = engineCaptureResponseRequestId(event.data);
       if (captureRequestId !== undefined) {
         const pending = this.captureRequests.get(captureRequestId);
@@ -208,7 +213,7 @@ export class SonareRealtimeEngineNode {
       } else if (isRecord(event.data) && event.data.type === 'syncError') {
         const syncError: SonareEngineSyncErrorMessage = {
           type: 'syncError',
-          syncType: String(event.data.syncType) as SonareEngineSyncErrorMessage['syncType'],
+          syncType: String(event.data.syncType),
           message: String(event.data.message ?? 'AudioWorklet sync failed'),
         };
         for (const listener of this.syncErrorListeners) {
@@ -268,43 +273,86 @@ export class SonareRealtimeEngineNode {
       );
     }
 
+    // Resolved before the transport branch, so a capacity the ring could not
+    // hold is refused by name whichever transport the caller ends up with.
+    const commandRingCapacity = requireIntegerOption(
+      options.commandRingCapacity,
+      128,
+      'commandRingCapacity',
+      1,
+    );
+    if (commandRingCapacity > 65536) {
+      throw new RangeError('commandRingCapacity must be at most 65536');
+    }
+    const telemetryRingCapacity = requireIntegerOption(
+      options.telemetryRingCapacity,
+      128,
+      'telemetryRingCapacity',
+      1,
+    );
+    const meterRingCapacity = requireIntegerOption(
+      options.meterRingCapacity,
+      128,
+      'meterRingCapacity',
+      1,
+    );
+    const scopeRingCapacity = requireIntegerOption(
+      options.scopeRingCapacity,
+      64,
+      'scopeRingCapacity',
+      1,
+    );
+    const scopeBands = requireIntegerOption(options.scopeBands, 48, 'scopeBands', 1);
+    const clipPageRequestRingCapacity = requireIntegerOption(
+      options.clipPageRequestRingCapacity,
+      128,
+      'clipPageRequestRingCapacity',
+      1,
+    );
+    const externalMidiRingCapacity = requireIntegerOption(
+      options.externalMidiRingCapacity,
+      256,
+      'externalMidiRingCapacity',
+      1,
+    );
     const commandRing =
-      mode === 'sab'
-        ? createSonareEngineCommandRingBuffer(options.commandRingCapacity ?? 128)
-        : undefined;
+      mode === 'sab' ? createSonareEngineCommandRingBuffer(commandRingCapacity) : undefined;
     const telemetryRing =
-      mode === 'sab'
-        ? createSonareEngineTelemetryRingBuffer(options.telemetryRingCapacity ?? 128)
-        : undefined;
+      mode === 'sab' ? createSonareEngineTelemetryRingBuffer(telemetryRingCapacity) : undefined;
     // Meter ring: the engine publishes meters into a SAB ring. Lock-free meter
     // delivery matches the telemetry path and keeps the audio render callback
     // allocation-free in SAB mode.
-    const meterRing =
-      mode === 'sab' ? createSonareMeterRingBuffer(options.meterRingCapacity ?? 128) : undefined;
+    const meterRing = mode === 'sab' ? createSonareMeterRingBuffer(meterRingCapacity) : undefined;
     // Scope ring (FFT spectrum + goniometer): opt-in. The per-block FFT is
     // heavier than the meter path, so it is created only when the caller
-    // requests scope telemetry via scopeIntervalFrames > 0.
-    const scopeIntervalFrames = Math.max(0, Math.floor(options.scopeIntervalFrames ?? 0));
+    // requests scope telemetry via scopeIntervalFrames > 0. Zero is the off
+    // switch, so the interval's floor is 0 rather than the capacities' 1.
+    const scopeIntervalFrames = requireIntegerOption(
+      options.scopeIntervalFrames,
+      0,
+      'scopeIntervalFrames',
+      0,
+    );
     const scopeRing =
       mode === 'sab' && scopeIntervalFrames > 0
-        ? createSonareScopeRingBuffer(options.scopeRingCapacity ?? 64, options.scopeBands ?? 48)
+        ? createSonareScopeRingBuffer(scopeRingCapacity, scopeBands)
         : undefined;
     // Paged-clip cache misses are a worklet-to-main-thread control signal. A
     // dedicated SPSC SAB ring keeps process() free of both embind request
     // objects and postMessage structured cloning.
     const clipPageRequestRing =
       mode === 'sab'
-        ? createSonareClipPageRequestRingBuffer(options.clipPageRequestRingCapacity ?? 128)
+        ? createSonareClipPageRequestRingBuffer(clipPageRequestRingCapacity)
         : undefined;
     const externalMidiRing =
-      mode === 'sab'
-        ? createSonareExternalMidiRingBuffer(options.externalMidiRingCapacity ?? 256)
-        : undefined;
-    const channelCount = Math.max(1, Math.floor(options.channelCount ?? 2));
+      mode === 'sab' ? createSonareExternalMidiRingBuffer(externalMidiRingCapacity) : undefined;
+    const channelCount = requireChannelCount(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 +377,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 +393,7 @@ export class SonareRealtimeEngineNode {
         audioWorklet,
         clipPageRequestsRealtimeSafe: mode === 'sab',
         externalMidiRealtimeSafe: mode === 'sab',
+        cueOutput,
         engineAbiVersion: detectedCapabilities?.engineAbiVersion,
         expectedEngineAbiVersion: detectedCapabilities?.expectedEngineAbiVersion,
         abiCompatible: detectedCapabilities?.abiCompatible,
@@ -595,6 +646,12 @@ export class SonareRealtimeEngineNode {
     this.scopeListeners.clear();
     this.midiOutListeners.clear();
     this.clipPageRequestListeners.clear();
+    this.syncErrorListeners.clear();
+    // The port outlives destroy(): the worklet tears itself down asynchronously
+    // after the 'destroy' message above, so a syncError already in flight would
+    // still be dispatched here. Detaching the handler is what makes the
+    // listener sets stay empty rather than being refilled by a late message.
+    this.node.port.onmessage = null;
   }
 
   private emitTelemetry(telemetry: SonareEngineTelemetryRecord): void {

package/src/worklet/engine-offline.ts

@@ -1,4 +1,5 @@
 import type { EngineCaptureStatus, EngineMarker, EngineTrackLane, RealtimeEngine } from '../index';
+import { requireChannelCount, requireInteger, requireIntegerOption } from './guards';
 import type { SonareEngineSyncCaptureMessage, SonareEngineTransportFacade } from './messages';
 
 /** Capture configuration options accepted by the engine's `configureCapture`. */
@@ -12,20 +13,22 @@ export interface CaptureOptions {
 
 /**
  * Normalizes capture options into the resolved config carried by the
- * `syncCapture` message, applying integer truncation and defaults.
+ * `syncCapture` message, applying defaults and refusing a non-integer count.
  *
  * @param options Raw capture options.
  * @param defaultChannels Channel count to use when `options.channels` is unset.
+ * @throws RangeError if a frame count, channel count or offset is not an integer.
  */
 export function buildCaptureConfig(
   options: CaptureOptions,
   defaultChannels: number,
 ): Omit<SonareEngineSyncCaptureMessage, 'type'> {
   return {
-    bufferFrames: Math.trunc(options.bufferFrames),
-    channels: Math.trunc(options.channels ?? defaultChannels),
+    // bufferFrames has no default; NaN makes the guard refuse an absent value.
+    bufferFrames: requireIntegerOption(options.bufferFrames, Number.NaN, 'bufferFrames', 1),
+    channels: requireChannelCount(options.channels, defaultChannels),
     source: options.source ?? 'output',
-    recordOffsetSamples: Math.trunc(options.recordOffsetSamples ?? 0),
+    recordOffsetSamples: requireInteger(options.recordOffsetSamples, 0, 'recordOffsetSamples'),
     inputMonitor: {
       enabled: Boolean(options.inputMonitor?.enabled),
       gain: options.inputMonitor?.gain ?? 1,
@@ -111,7 +114,7 @@ export function normalizeTrackLanes(
   const ids: number[] = [];
   for (const entry of entries) {
     if (!Number.isInteger(entry.trackId) || entry.trackId <= 0) {
-      throw new Error(`Invalid track id for mixer lane: ${String(entry.trackId)}`);
+      throw new RangeError(`Invalid track id for mixer lane: ${String(entry.trackId)}`);
     }
     ids.push(entry.trackId);
   }
@@ -145,12 +148,15 @@ export function resolveMarkerSet(
   const seen = new Set<number>();
   let counter = nextMarkerId;
   for (const marker of markers) {
-    if (!Number.isFinite(marker.ppq)) {
-      throw new Error(`Invalid marker ppq: ${String(marker.ppq)}`);
+    // Non-negative as well as finite, which is the domain the native setter
+    // enforces; checking only finiteness here hands a negative ppq on to be
+    // refused a layer down, under that layer's name for the argument.
+    if (!Number.isFinite(marker.ppq) || marker.ppq < 0) {
+      throw new RangeError(`Invalid marker ppq: ${String(marker.ppq)}`);
     }
     if (marker.id !== undefined) {
       if (!Number.isInteger(marker.id) || marker.id <= 0) {
-        throw new Error(`Invalid marker id: ${String(marker.id)}`);
+        throw new RangeError(`Invalid marker id: ${String(marker.id)}`);
       }
       if (seen.has(marker.id)) {
         throw new Error(`Duplicate marker id: ${marker.id}`);

package/src/worklet/engine-parameter-facade.ts

@@ -190,6 +190,27 @@ export function resolveBusInsertAutomationId(
   return ctx.offlineEngine.resolveBusInsertAutomationId(busId, insertIndex, paramName);
 }
 
+/**
+ * Resolves a hosted instrument's continuous parameter to its reserved
+ * instrument-automation id, so an instrument parameter is driven from a
+ * breakpoint lane at audio-block precision like a strip insert.
+ *
+ * The instrument must already be bound on the offline engine for the
+ * destination (the worklet mirrors every instrument sync onto it), otherwise
+ * the resolve returns -1.
+ *
+ * @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.
+ */
+export function resolveInstrumentAutomationId(
+  ctx: EngineParameterContext,
+  destinationId: number,
+  paramName: string,
+): number {
+  return ctx.offlineEngine.resolveInstrumentAutomationId(destinationId, paramName);
+}
+
 /**
  * Returns the number of automation lanes installed on the engine, including
  * lanes whose breakpoint list is currently empty.