@libraz/libsonare 1.7.2 → 1.8.1

package/src/worklet/engine-node.ts

@@ -9,6 +9,10 @@ import {
   isEngineTransportResponseMessage,
   isExternalMidiBatchMessage,
   isMeterSnapshot,
+  isScopeSnapshot,
+  requireChannelCount,
+  requireIntegerOption,
+  resolveScopeBandCount,
 } from './guards';
 import type {
   SonareEngineCaptureRequestMessage,
@@ -29,6 +33,7 @@ import {
   createSonareMeterRingBuffer,
   createSonareScopeRingBuffer,
   isRecord,
+  isUint32Slot,
   pushSonareEngineCommandRingBuffer,
   readSonareClipPageRequestRingBuffer,
   readSonareEngineTelemetryRingBuffer,
@@ -63,30 +68,27 @@ 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 (
     !Number.isSafeInteger(type) ||
     type < SonareEngineCommandType.SetParam ||
     (type > SonareEngineCommandType.SeekMarker &&
-      type !== SonareEngineCommandType.SetTrackMonitorMode)
+      type !== SonareEngineCommandType.SetTrackMonitorMode &&
+      type !== SonareEngineCommandType.ResetMasterLoudnessMeter)
   ) {
     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 +174,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);
@@ -201,6 +209,8 @@ export class SonareRealtimeEngineNode {
         this.emitTelemetry(event.data);
       } else if (isMeterSnapshot(event.data)) {
         this.emitMeter(event.data);
+      } else if (isScopeSnapshot(event.data)) {
+        this.emitScope(event.data);
       } else if (isExternalMidiBatchMessage(event.data)) {
         this.emitMidiOut(event.data.events);
       } else if (isClipPageRequestMessage(event.data)) {
@@ -208,7 +218,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,44 +278,93 @@ export class SonareRealtimeEngineNode {
       );
     }
 
+    const meterIntervalFrames = requireIntegerOption(
+      options.meterIntervalFrames,
+      2048,
+      'meterIntervalFrames',
+      0,
+    );
+
+    // 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 = resolveScopeBandCount(options.scopeBands);
+    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,
+      meterIntervalFrames,
       cueOutput,
       commandSharedBuffer: commandRing?.sharedBuffer,
       commandRingCapacity: commandRing?.capacity,
@@ -315,8 +374,8 @@ export class SonareRealtimeEngineNode {
       meterRingCapacity: meterRing?.capacity,
       scopeSharedBuffer: scopeRing?.sharedBuffer,
       scopeRingCapacity: scopeRing?.capacity,
-      scopeBands: scopeRing?.bands,
-      scopeIntervalFrames: scopeRing ? scopeIntervalFrames : undefined,
+      scopeBands: scopeIntervalFrames > 0 ? (scopeRing?.bands ?? scopeBands) : undefined,
+      scopeIntervalFrames: scopeIntervalFrames > 0 ? scopeIntervalFrames : undefined,
       clipPageRequestSharedBuffer: clipPageRequestRing?.sharedBuffer,
       clipPageRequestRingCapacity: clipPageRequestRing?.capacity,
       externalMidiSharedBuffer: externalMidiRing?.sharedBuffer,
@@ -370,6 +429,11 @@ export class SonareRealtimeEngineNode {
     return this.sendCommand({ type: SonareEngineCommandType.TransportPlay, sampleTime });
   }
 
+  /** Queues a reset of the master's integrated-loudness accumulator. */
+  resetMasterLoudnessMeter(sampleTime = -1): boolean {
+    return this.sendCommand({ type: SonareEngineCommandType.ResetMasterLoudnessMeter, sampleTime });
+  }
+
   stop(sampleTime = -1): boolean {
     return this.sendCommand({ type: SonareEngineCommandType.TransportStop, sampleTime });
   }
@@ -600,6 +664,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.