@libraz/libsonare 1.8.1 → 1.8.2

package/src/worklet/engine-node.ts

@@ -5,6 +5,7 @@ import {
   isClipPageRequestMessage,
   isEngineCaptureResponseForOperation,
   isEngineCaptureResponseMessage,
+  isEngineInsertGainReductionResponseMessage,
   isEngineTelemetryRecord,
   isEngineTransportResponseMessage,
   isExternalMidiBatchMessage,
@@ -144,6 +145,14 @@ export class SonareRealtimeEngineNode {
       reject: (reason?: unknown) => void;
     }
   >();
+  private insertGainReductionRequestId = 1;
+  private readonly insertGainReductionRequests = new Map<
+    number,
+    {
+      resolve: (values: number[]) => void;
+      reject: (reason?: unknown) => void;
+    }
+  >();
   private resolveReady!: () => void;
   private rejectReady!: (reason?: unknown) => void;
   private destroyed = false;
@@ -205,6 +214,16 @@ export class SonareRealtimeEngineNode {
             pending.reject(new Error(event.data.error ?? 'Transport request failed'));
           }
         }
+      } else if (isEngineInsertGainReductionResponseMessage(event.data)) {
+        const pending = this.insertGainReductionRequests.get(event.data.requestId);
+        if (pending) {
+          this.insertGainReductionRequests.delete(event.data.requestId);
+          if (event.data.ok && Array.isArray(event.data.values)) {
+            pending.resolve(event.data.values);
+          } else {
+            pending.reject(new Error(event.data.error ?? 'Insert gain reduction request failed'));
+          }
+        }
       } else if (isEngineTelemetryRecord(event.data)) {
         this.emitTelemetry(event.data);
       } else if (isMeterSnapshot(event.data)) {
@@ -659,6 +678,10 @@ export class SonareRealtimeEngineNode {
       pending.reject(new Error('Realtime engine node is destroyed.'));
     }
     this.transportRequests.clear();
+    for (const pending of this.insertGainReductionRequests.values()) {
+      pending.reject(new Error('Realtime engine node is destroyed.'));
+    }
+    this.insertGainReductionRequests.clear();
     this.telemetryListeners.clear();
     this.meterListeners.clear();
     this.scopeListeners.clear();
@@ -728,6 +751,30 @@ export class SonareRealtimeEngineNode {
     }
   }
 
+  /**
+   * Reads one target's per-insert gain reduction (dB, each <= 0, pre-to-post insert order)
+   * from the worklet. Works in both ring and postMessage meter modes; rejects when the
+   * target is invalid or mixing is not compiled in.
+   */
+  pollInsertGainReduction(targetId: number): Promise<number[]> {
+    if (this.destroyed) {
+      return Promise.reject(new Error('Realtime engine node is destroyed.'));
+    }
+    const requestId = this.insertGainReductionRequestId++;
+    let rejectRequest!: (reason?: unknown) => void;
+    const promise = new Promise<number[]>((resolve, reject) => {
+      rejectRequest = reject;
+      this.insertGainReductionRequests.set(requestId, { resolve, reject });
+    });
+    try {
+      this.node.port.postMessage({ type: 'insertGainReductionRequest', requestId, targetId });
+    } catch (error) {
+      this.insertGainReductionRequests.delete(requestId);
+      rejectRequest(error);
+    }
+    return promise;
+  }
+
   private emitScope(scope: SonareWorkletScopeSnapshot): void {
     for (const listener of this.scopeListeners) {
       listener(scope);

package/src/worklet/engine-processor.ts

@@ -14,6 +14,8 @@ import {
   resolveMetronomeConfig,
   type SonareEngineCaptureRequestMessage,
   type SonareEngineCaptureResponseMessageInternal,
+  type SonareEngineInsertGainReductionRequestMessage,
+  type SonareEngineInsertGainReductionResponseMessage,
   type SonareEngineSyncMessage,
   type SonareEngineTransportRequestMessage,
   type SonareEngineTransportResponseMessage,
@@ -46,6 +48,7 @@ import {
   type SonareEngineTelemetryRecord,
   type SonareEngineTelemetryRingBuffer,
   SonareEngineTelemetryType,
+  type SonareWorkletMeterSnapshot,
   type SonareWorkletScopeSnapshot,
   scopeRingFromSharedBuffer,
   telemetryFromEngine,
@@ -682,6 +685,9 @@ export class SonareRealtimeEngineWorkletProcessor {
       case 'syncTrackStripDualPan':
         this.engine.setTrackStripDualPan(message.trackId, message.leftPan, message.rightPan);
         break;
+      case 'syncTrackStripSurroundPan':
+        this.engine.setTrackStripSurroundPan(message.trackId, message.pan);
+        break;
       case 'syncBusStripPan':
         this.engine.setBusStripPan(message.busId, message.pan);
         break;
@@ -774,7 +780,11 @@ export class SonareRealtimeEngineWorkletProcessor {
         );
         break;
       case 'syncMidiUmp':
-        this.engine.pushMidiUmp(message.destinationId, [message.word0], message.renderFrame);
+        this.engine.pushMidiUmp(
+          message.destinationId,
+          message.words ?? [message.word0],
+          message.renderFrame,
+        );
         break;
       case 'syncMidiSysex':
         this.engine.pushMidiSysex(message.destinationId, message.data, message.renderFrame);
@@ -852,6 +862,9 @@ export class SonareRealtimeEngineWorkletProcessor {
           message.portTimeSamples,
         );
         break;
+      case 'syncMidiInputUmp':
+        this.engine.pushMidiInputUmp(message.words, message.portTimeSamples);
+        break;
     }
   }
 
@@ -931,6 +944,27 @@ export class SonareRealtimeEngineWorkletProcessor {
     }
   }
 
+  receiveInsertGainReductionRequest(message: SonareEngineInsertGainReductionRequestMessage): void {
+    if (this.closed) {
+      return;
+    }
+    try {
+      this.transport?.postMessage?.({
+        type: 'insertGainReductionResponse',
+        requestId: message.requestId,
+        ok: true,
+        values: this.engine.meterTargetInsertGainReduction(message.targetId),
+      } satisfies SonareEngineInsertGainReductionResponseMessage);
+    } catch (error) {
+      this.transport?.postMessage?.({
+        type: 'insertGainReductionResponse',
+        requestId: message.requestId,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      } satisfies SonareEngineInsertGainReductionResponseMessage);
+    }
+  }
+
   destroy(): void {
     if (!this.closed) {
       this.clearPagedClipProviders();
@@ -1151,6 +1185,8 @@ export class SonareRealtimeEngineWorkletProcessor {
       }
       return;
     }
+    const delivered: SonareWorkletMeterSnapshot[] = [];
+    const newestByTarget = new Map<number, SonareWorkletMeterSnapshot>();
     for (const item of this.engine.drainMeterTelemetry(64)) {
       const meter = meterFromEngine(item);
       if (
@@ -1162,6 +1198,15 @@ export class SonareRealtimeEngineWorkletProcessor {
       if (meter.frame !== this.lastMeterFrame) {
         this.lastMeterFrame = meter.frame;
       }
+      delivered.push(meter);
+      newestByTarget.set(meter.targetId, meter);
+    }
+    for (const meter of delivered) {
+      // The board holds only the latest block, so only the newest record per
+      // target in this drain can carry it; the ring layout is fixed and cannot.
+      if (newestByTarget.get(meter.targetId) === meter) {
+        meter.insertGainReductionDb = this.engine.meterTargetInsertGainReduction(meter.targetId);
+      }
       // 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

package/src/worklet/engine-register.ts

@@ -5,6 +5,7 @@ import { SonareRealtimeEngineWorkletProcessor } from './engine-processor';
 import {
   isEngineCaptureRequestMessage,
   isEngineCommandRecord,
+  isEngineInsertGainReductionRequestMessage,
   isEngineSyncMessage,
   isEngineTransportRequestMessage,
 } from './guards';
@@ -82,6 +83,8 @@ export function registerSonareRealtimeEngineWorkletProcessor(
         bridge.receiveCaptureRequest(data);
       } else if (isEngineTransportRequestMessage(data)) {
         bridge.receiveTransportRequest(data);
+      } else if (isEngineInsertGainReductionRequestMessage(data)) {
+        bridge.receiveInsertGainReductionRequest(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.

package/src/worklet/engine-strips.ts

@@ -1,5 +1,6 @@
 import { panLawCode, panModeCode } from '../codes';
-import type { EqBand, PanLawInput, PanMode, RealtimeEngine } from '../index';
+import type { EqBand, PanLawInput, PanMode, RealtimeEngine, UmpWords } from '../index';
+import type { SurroundPan } from '../public_types';
 import type { InsertParamOverrideMap } from './engine-mixer-facade';
 import {
   emptyStripJson,
@@ -205,6 +206,26 @@ export function setTrackStripDualPan(
   ctx.postSync({ type: 'syncTrackStripDualPan', trackId, leftPan, rightPan });
 }
 
+export function setTrackStripSurroundPan(
+  ctx: EngineStripContext,
+  target: string | number,
+  pan: SurroundPan,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  ctx.offlineEngine.setTrackStripSurroundPan(trackId, pan);
+  const resolved = {
+    azimuth: pan.azimuth ?? 0,
+    elevation: pan.elevation ?? 0,
+    divergence: pan.divergence ?? 0,
+    lfe: pan.lfe ?? 0,
+    distance: pan.distance === undefined || pan.distance <= 0 ? 1 : pan.distance,
+  };
+  mergeStripJson(ctx, { kind: 'track', trackId }, (entry) => {
+    entry.surroundPan = resolved;
+  });
+  ctx.postSync({ type: 'syncTrackStripSurroundPan', trackId, pan: resolved });
+}
+
 export function setTrackStripChannelDelaySamples(
   ctx: EngineStripContext,
   target: string | number,
@@ -499,12 +520,18 @@ export function pushMidiPolyPressure(
 export function pushMidiUmp(
   ctx: EngineStripContext,
   trackId: string | number,
-  word0: number,
+  word0: number | UmpWords,
   renderFrame: number,
 ): void {
   const destinationId = ctx.resolveTargetId(trackId);
-  ctx.offlineEngine.pushMidiUmp(destinationId, [word0], renderFrame);
-  ctx.postSync({ type: 'syncMidiUmp', destinationId, word0, renderFrame });
+  if (typeof word0 === 'number') {
+    ctx.offlineEngine.pushMidiUmp(destinationId, word0, renderFrame);
+    ctx.postSync({ type: 'syncMidiUmp', destinationId, word0, renderFrame });
+    return;
+  }
+  const words = word0 instanceof Uint32Array ? new Uint32Array(word0) : word0.slice();
+  ctx.offlineEngine.pushMidiUmp(destinationId, words, renderFrame);
+  ctx.postSync({ type: 'syncMidiUmp', destinationId, words, renderFrame });
 }
 
 export function setBuiltinInstrument(

package/src/worklet/engine.ts

@@ -23,9 +23,11 @@ import type {
   PanLaw,
   PanMode,
   SidechainSourceKind,
+  UmpWords,
 } from '../index';
 import { RealtimeEngine } from '../index';
 import { createOpfsClipPageProvider, type OpfsClipPageProviderBinding } from '../opfs_clip_pages';
+import type { SurroundPan } from '../public_types';
 import type { ClipPageProvider } from '../realtime_engine';
 import type { EngineAutomationContext } from './engine-automation';
 import * as automation from './engine-automation';
@@ -505,7 +507,9 @@ export class SonareEngine {
   /**
    * Keys one insert of a lane strip from another lane's post-strip pre-fader
    * audio (ducking/sidechainRouter inserts). sourceTarget null removes the
-   * binding.
+   * binding. Throws, leaving the existing bindings unchanged, for a lane keying
+   * itself or a binding that would close a cycle over the lane bindings; a
+   * refused binding is never recorded, so it is not replayed on resync.
    */
   setLaneSidechain(
     target: string | number,
@@ -611,6 +615,15 @@ export class SonareEngine {
     strips.setTrackStripDualPan(this.stripContext, target, leftPan, rightPan);
   }
 
+  /**
+   * Sets a track lane strip's surround placement (glitch-free, 5 ms placement
+   * glide). Takes effect on a destination wider than stereo, so set `channelCount`
+   * to the layout's plane count. Omitted fields default to a centered point source.
+   */
+  setTrackStripSurroundPan(target: string | number, pan: SurroundPan): void {
+    strips.setTrackStripSurroundPan(this.stripContext, target, pan);
+  }
+
   setTrackStripChannelDelaySamples(target: string | number, delaySamples: number): void {
     strips.setTrackStripChannelDelaySamples(this.stripContext, target, delaySamples);
   }
@@ -1031,8 +1044,8 @@ export class SonareEngine {
     );
   }
 
-  pushMidiUmp(trackId: string | number, word0: number, renderFrame = -1): void {
-    strips.pushMidiUmp(this.stripContext, trackId, word0, renderFrame);
+  pushMidiUmp(trackId: string | number, words: number | UmpWords, renderFrame = -1): void {
+    strips.pushMidiUmp(this.stripContext, trackId, words, renderFrame);
   }
 
   pushMidiSysex(trackId: string | number, data: Uint8Array, renderFrame = -1): void {
@@ -1167,6 +1180,12 @@ export class SonareEngine {
     });
   }
 
+  pushMidiInputUmp(words: UmpWords, portTimeSamples = 0): void {
+    const copiedWords = words instanceof Uint32Array ? new Uint32Array(words) : words.slice();
+    this.offlineEngine.pushMidiInputUmp(copiedWords, portTimeSamples);
+    this.postSync({ type: 'syncMidiInputUmp', words: copiedWords, portTimeSamples });
+  }
+
   pushMidiPanic(renderFrame = -1): void {
     this.offlineEngine.pushMidiPanic(renderFrame);
     this.postSync({ type: 'syncMidiPanic', renderFrame });
@@ -1288,6 +1307,11 @@ export class SonareEngine {
     return this.realtimeNode.pollScope();
   }
 
+  /** Per-insert gain reduction for a meter target; see {@link SonareRealtimeEngineNode.pollInsertGainReduction}. */
+  pollInsertGainReduction(targetId: number): Promise<number[]> {
+    return this.realtimeNode.pollInsertGainReduction(targetId);
+  }
+
   destroy(): void {
     if (this.destroyed) {
       return;

package/src/worklet/guards.ts

@@ -3,6 +3,8 @@ import type {
   SonareEngineCaptureRequestMessage,
   SonareEngineCaptureResponseMessageInternal,
   SonareEngineClipPageRequestMessage,
+  SonareEngineInsertGainReductionRequestMessage,
+  SonareEngineInsertGainReductionResponseMessage,
   SonareEngineSyncMessage,
   SonareEngineTransportRequestMessage,
   SonareEngineTransportResponseMessage,
@@ -86,6 +88,7 @@ export const ENGINE_SYNC_MESSAGE_TYPES: Record<SonareEngineSyncMessage['type'],
   syncMidiInputPitchBend: true,
   syncMidiInputPolyPressure: true,
   syncMidiInputSource: true,
+  syncMidiInputUmp: true,
   syncMidiNoteOff: true,
   syncMidiNoteOn: true,
   syncMidiPanic: true,
@@ -106,6 +109,7 @@ export const ENGINE_SYNC_MESSAGE_TYPES: Record<SonareEngineSyncMessage['type'],
   syncTrackStripPan: true,
   syncTrackStripPanLaw: true,
   syncTrackStripPanMode: true,
+  syncTrackStripSurroundPan: true,
   syncWarpVoiceCapacity: true,
 };
 
@@ -254,6 +258,28 @@ export function isEngineTransportResponseMessage(
   );
 }
 
+export function isEngineInsertGainReductionRequestMessage(
+  value: unknown,
+): value is SonareEngineInsertGainReductionRequestMessage {
+  return (
+    isRecord(value) &&
+    value.type === 'insertGainReductionRequest' &&
+    typeof value.requestId === 'number' &&
+    typeof value.targetId === 'number'
+  );
+}
+
+export function isEngineInsertGainReductionResponseMessage(
+  value: unknown,
+): value is SonareEngineInsertGainReductionResponseMessage {
+  return (
+    isRecord(value) &&
+    value.type === 'insertGainReductionResponse' &&
+    typeof value.requestId === 'number' &&
+    typeof value.ok === 'boolean'
+  );
+}
+
 export function isRealtimeVoiceChangerMessage(
   value: unknown,
 ): value is SonareRealtimeVoiceChangerMessage {

package/src/worklet/messages.ts

@@ -15,8 +15,9 @@ import type {
   PlaybackRendererConfig,
   RealtimeVoiceChangerConfigInput,
   RealtimeVoiceChangerPodConfig,
+  UmpWords,
 } from '../index';
-import type { AutomationCurve } from '../public_types';
+import type { AutomationCurve, SurroundPan } from '../public_types';
 import type {
   SonareEngineCommandRecord,
   SonareEngineTelemetryRecord,
@@ -45,6 +46,18 @@ export interface SonareRealtimeEngineWorkletProcessorOptions {
   initialCommands?: SonareEngineCommandRecord[];
   sampleRate?: number;
   blockSize?: number;
+  /**
+   * Output plane count (default 2). Planes follow the canonical order
+   * L R C LFE Ls Rs [Lss Rss] for 6 (5.1) and 8 (7.1) planes.
+   *
+   * The Web Audio default destination is 2-channel `'speakers'`, so a wider
+   * output is mixed down to stereo unless the app raises
+   * `audioContext.destination.channelCount` (up to its `maxChannelCount`) to
+   * match. Interpretation matters only while the counts differ: `'speakers'`
+   * applies the spec's down-mix for mono, stereo, quad and 5.1 sources only,
+   * and `'discrete'` copies the first planes and drops the rest. With equal
+   * counts the planes pass through unchanged in either mode.
+   */
   channelCount?: number;
   meterIntervalFrames?: number;
   commandSharedBuffer?: SharedArrayBuffer;
@@ -301,6 +314,7 @@ export interface WorkletTransport {
       | SonareWorkletTransportMessage
       | SonareEngineCaptureResponseMessageInternal
       | SonareEngineTransportResponseMessage
+      | SonareEngineInsertGainReductionResponseMessage
       | SonareEngineSyncErrorMessage,
     transfer?: Transferable[],
   ) => void;
@@ -633,6 +647,12 @@ export interface SonareEngineSyncTrackStripDualPanMessage {
   rightPan: number;
 }
 
+export interface SonareEngineSyncTrackStripSurroundPanMessage {
+  type: 'syncTrackStripSurroundPan';
+  trackId: number;
+  pan: Required<SurroundPan>;
+}
+
 export interface SonareEngineSyncBusStripPanMessage {
   type: 'syncBusStripPan';
   busId: number;
@@ -721,13 +741,26 @@ export interface SonareEngineSyncMidiCcMessage {
   renderFrame: number;
 }
 
-export interface SonareEngineSyncMidiUmpMessage {
+export interface SonareEngineSyncMidiUmpWordMessage {
   type: 'syncMidiUmp';
   destinationId: number;
   word0: number;
+  words?: never;
   renderFrame: number;
 }
 
+export interface SonareEngineSyncMidiUmpWordsMessage {
+  type: 'syncMidiUmp';
+  destinationId: number;
+  word0?: never;
+  words: UmpWords;
+  renderFrame: number;
+}
+
+export type SonareEngineSyncMidiUmpMessage =
+  | SonareEngineSyncMidiUmpWordMessage
+  | SonareEngineSyncMidiUmpWordsMessage;
+
 /**
  * One of the three per-note expression dimensions, addressed to a destination.
  * `data0`/`data1` carry the dimension's own payload the way the live-input
@@ -796,6 +829,12 @@ export interface SonareEngineSyncMidiInputEventMessage {
   portTimeSamples: number;
 }
 
+export interface SonareEngineSyncMidiInputUmpMessage {
+  type: 'syncMidiInputUmp';
+  words: UmpWords;
+  portTimeSamples: number;
+}
+
 /** Releases the realtime engine and all worklet-owned clip buffers. */
 export interface SonareEngineDestroyMessage {
   type: 'destroy';
@@ -839,6 +878,7 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncTrackStripPanLawMessage
   | SonareEngineSyncTrackStripPanModeMessage
   | SonareEngineSyncTrackStripDualPanMessage
+  | SonareEngineSyncTrackStripSurroundPanMessage
   | SonareEngineSyncBusStripPanMessage
   | SonareEngineSyncBusStripPanLawMessage
   | SonareEngineSyncBusStripPanModeMessage
@@ -860,6 +900,7 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncMidiInputSourceMessage
   | SonareEngineSyncMidiCcBindingMessage
   | SonareEngineSyncMidiInputEventMessage
+  | SonareEngineSyncMidiInputUmpMessage
   | SonareEngineDestroyMessage;
 
 export interface WorkletPort {
@@ -937,3 +978,19 @@ export interface SonareEngineTransportResponseMessage {
   state?: EngineTransportState;
   error?: string;
 }
+
+/** Asks the worklet for one target's per-insert gain reduction (any meter delivery mode). */
+export interface SonareEngineInsertGainReductionRequestMessage {
+  type: 'insertGainReductionRequest';
+  requestId: number;
+  targetId: number;
+}
+
+/** Reply to {@link SonareEngineInsertGainReductionRequestMessage}; `values` is present when `ok`. */
+export interface SonareEngineInsertGainReductionResponseMessage {
+  type: 'insertGainReductionResponse';
+  requestId: number;
+  ok: boolean;
+  values?: number[];
+  error?: string;
+}

package/src/worklet/protocol.ts

@@ -45,6 +45,16 @@ export interface SonareWorkletMeterSnapshot {
   inputPeakDbL: number;
   /** Maximum pre-trim input peak for the right channel, in dBFS. */
   inputPeakDbR: number;
+  /**
+   * Per-insert gain reduction in dB (each <= 0) of the target's strip, in combined
+   * pre-to-post insert order, folded to the deepest value across the sub-blocks of the
+   * latest committed host block. It describes that latest block as of the drain, not
+   * necessarily this record's own block, so it is attached only to the newest record per
+   * target within one drain; older backlogged records omit it. Present only on snapshots
+   * delivered over postMessage; the SharedArrayBuffer meter ring has a fixed layout that
+   * does not carry it, so ring hosts read it with `pollInsertGainReduction(targetId)`.
+   */
+  insertGainReductionDb?: number[];
 }
 
 export interface SonareWorkletSpectrumSnapshot {

package/src/worklet.ts

@@ -24,6 +24,8 @@ export type {
   SonareEngineCaptureRequestMessage,
   SonareEngineCaptureResponseMessage,
   SonareEngineClipPageRequestMessage,
+  SonareEngineInsertGainReductionRequestMessage,
+  SonareEngineInsertGainReductionResponseMessage,
   SonareEngineSyncAutomationMessage,
   SonareEngineSyncBuiltinInstrumentMessage,
   SonareEngineSyncBusStripEqBandMessage,