@libraz/libsonare 1.6.0 → 1.7.0

package/src/quick_analysis.ts

@@ -29,7 +29,12 @@ import type {
 import { Mode, PitchClass } from './public_types';
 import type { ProgressCallback, WasmAcousticResult } from './sonare.js';
 import type { ValidateOptions } from './validation';
-import { assertNonNegativeInteger, assertSampleRate, assertSamples } from './validation';
+import {
+  assertFiniteScalar,
+  assertNonNegativeInteger,
+  assertSampleRate,
+  assertSamples,
+} from './validation';
 
 function requireModule() {
   return getSonareModule();
@@ -81,6 +86,7 @@ export interface ChordFunctionalAnalysisRequest extends DetectChordsRequest {
 /** Canonical request form for impulse-response analysis. */
 export interface AnalyzeImpulseResponseRequest extends SamplesRequest {
   nOctaveBands?: number;
+  minDecayDb?: number;
 }
 
 /** Canonical request form for acoustic analysis. */
@@ -435,23 +441,35 @@ export function analyzeImpulseResponse(
   samples: Float32Array,
   sampleRate?: number,
   nOctaveBands?: number,
+  minDecayDb?: number,
 ): AcousticResult;
 export function analyzeImpulseResponse(
   samples: Float32Array | AnalyzeImpulseResponseRequest,
   sampleRate = 48000,
   nOctaveBands = 6,
+  minDecayDb?: number,
 ): AcousticResult {
-  const request = samples instanceof Float32Array ? { samples, sampleRate, nOctaveBands } : samples;
+  const request =
+    samples instanceof Float32Array ? { samples, sampleRate, nOctaveBands, minDecayDb } : samples;
+  if (request.minDecayDb === null) {
+    throw new TypeError('analyzeImpulseResponse: minDecayDb must be a finite number');
+  }
+  const resolvedMinDecayDb = request.minDecayDb === undefined ? 30.0 : request.minDecayDb;
+  assertFiniteScalar('analyzeImpulseResponse', resolvedMinDecayDb, 'minDecayDb');
+  if (resolvedMinDecayDb <= 0) {
+    throw new RangeError('analyzeImpulseResponse: minDecayDb must be greater than zero');
+  }
   validateAnalysisInput(
     'analyzeImpulseResponse',
     request.samples,
     request.sampleRate ?? 48000,
     request,
   );
-  const result: WasmAcousticResult = requireModule().analyzeImpulseResponse(
+  const result: WasmAcousticResult = requireModule().analyzeImpulseResponseEx(
     request.samples,
     request.sampleRate ?? 48000,
     request.nOctaveBands ?? 6,
+    resolvedMinDecayDb,
   );
   return result;
 }

package/src/realtime_engine.ts

@@ -1,8 +1,8 @@
-import { panLawCode, panModeCode, sendTimingCode } from './codes';
+import { panLawCode, panModeCode, sendTimingCode, trackMonitorModeCode } from './codes';
 import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type { ProjectMidiCcBinding, SynthPatch } from './project';
-import type { EqBand, PanLaw, PanMode, SendTiming } from './public_types';
+import type { EqBand, PanLawInput, PanMode, SendTiming } from './public_types';
 import type {
   WasmClipPageRequest,
   WasmEngineAutomationPoint,
@@ -78,6 +78,12 @@ export interface EngineTrackLane {
   sourceChannelLayout?: number;
 }
 
+/** Per-track cue/monitor tap mode: off, pre-fader listen, or after-fader listen. */
+export type EngineTrackMonitorMode = 'off' | 'pfl' | 'afl' | 0 | 1 | 2;
+
+/** Short alias for {@link EngineTrackMonitorMode}. */
+export type TrackMonitorMode = EngineTrackMonitorMode;
+
 export interface EngineBus {
   busId: number;
   gainDb?: number;
@@ -219,6 +225,11 @@ export class RealtimeEngine {
     this.native.setSoloMute(laneIndex, solo, mute, renderFrame);
   }
 
+  /** Queue a per-track PFL/AFL monitor tap mode change. */
+  setTrackMonitorMode(laneIndex: number, mode: EngineTrackMonitorMode, renderFrame = -1): void {
+    this.native.setTrackMonitorMode(laneIndex, trackMonitorModeCode(mode), renderFrame);
+  }
+
   setMidiClips(clips: readonly EngineMidiClipSchedule[]): void {
     this.native.setMidiClips(clips);
   }
@@ -831,7 +842,7 @@ export class RealtimeEngine {
   }
 
   /** Sets a track lane strip's pan law in realtime. */
-  setTrackStripPanLaw(trackId: number, panLaw: PanLaw | number): void {
+  setTrackStripPanLaw(trackId: number, panLaw: PanLawInput): void {
     this.native.setTrackStripPanLaw(trackId, panLawCode(panLaw));
   }
 

package/src/sonare.js.d.ts

@@ -699,6 +699,10 @@ export interface WasmProjectSource {
   storageHandleId: number;
   sampleRateHint: number;
   nameOrUri: string;
+  /** Owning content hash for audio sources; empty for MIDI sources. */
+  contentHash: string;
+  /** External source-separation role for audio sources; empty for MIDI sources. */
+  externalStemRole: string;
 }
 
 export interface WasmEngineMetronomeConfig {
@@ -914,6 +918,7 @@ export interface WasmRealtimeEngine {
   setParameterSmoothed: (paramId: number, value: number, renderFrame: number) => void;
   setParamSmoothingMs: (smoothingMs: number) => void;
   setSoloMute: (laneIndex: number, solo: boolean, mute: boolean, renderFrame: number) => void;
+  setTrackMonitorMode: (laneIndex: number, mode: number, renderFrame: number) => void;
   getTransportState: () => WasmEngineTransportState;
   play: (renderFrame: number) => void;
   stop: (renderFrame: number) => void;
@@ -1234,6 +1239,12 @@ export interface SonareModule {
     sampleRate: number,
     nOctaveBands: number,
   ) => WasmAcousticResult;
+  analyzeImpulseResponseEx: (
+    samples: Float32Array,
+    sampleRate: number,
+    nOctaveBands: number,
+    minDecayDb: number,
+  ) => WasmAcousticResult;
   detectAcoustic: (
     samples: Float32Array,
     sampleRate: number,
@@ -1473,12 +1484,30 @@ export interface SonareModule {
     kernelHarmonic: number,
     kernelPercussive: number,
   ) => WasmHpssResult;
+  hpssEx: (
+    samples: Float32Array,
+    sampleRate: number,
+    kernelHarmonic: number,
+    kernelPercussive: number,
+    nFft: number,
+    hopLength: number,
+    hardMask: boolean,
+  ) => WasmHpssResult;
   hpssWithResidual: (
     samples: Float32Array,
     sampleRate: number,
     kernelHarmonic: number,
     kernelPercussive: number,
   ) => WasmHpssWithResidualResult;
+  hpssWithResidualEx: (
+    samples: Float32Array,
+    sampleRate: number,
+    kernelHarmonic: number,
+    kernelPercussive: number,
+    nFft: number,
+    hopLength: number,
+    hardMask: boolean,
+  ) => WasmHpssWithResidualResult;
   decompose: (
     s: Float32Array,
     nFeatures: number,
@@ -1520,7 +1549,21 @@ export interface SonareModule {
   harmonic: (samples: Float32Array, sampleRate: number) => Float32Array;
   percussive: (samples: Float32Array, sampleRate: number) => Float32Array;
   timeStretch: (samples: Float32Array, sampleRate: number, rate: number) => Float32Array;
+  timeStretchEx: (
+    samples: Float32Array,
+    sampleRate: number,
+    rate: number,
+    nFft: number,
+    hopLength: number,
+  ) => Float32Array;
   pitchShift: (samples: Float32Array, sampleRate: number, semitones: number) => Float32Array;
+  pitchShiftEx: (
+    samples: Float32Array,
+    sampleRate: number,
+    semitones: number,
+    nFft: number,
+    hopLength: number,
+  ) => Float32Array;
   pitchCorrectToMidi: (
     samples: Float32Array,
     sampleRate: number,
@@ -1582,6 +1625,12 @@ export interface SonareModule {
     channels: number,
   ) => Float32Array;
   normalize: (samples: Float32Array, sampleRate: number, targetDb: number) => Float32Array;
+  normalizeEx: (
+    samples: Float32Array,
+    sampleRate: number,
+    targetDb: number,
+    mode: string,
+  ) => Float32Array;
   mastering: (
     samples: Float32Array,
     sampleRate: number,
@@ -1760,6 +1809,13 @@ export interface SonareModule {
     options: Record<string, unknown>,
   ) => WasmMixResult;
   trim: (samples: Float32Array, sampleRate: number, thresholdDb: number) => Float32Array;
+  trimEx: (
+    samples: Float32Array,
+    sampleRate: number,
+    thresholdDb: number,
+    frameLength: number,
+    hopLength: number,
+  ) => Float32Array;
   spectralEdit: (
     samples: Float32Array,
     sampleRate: number,
@@ -2190,6 +2246,14 @@ export interface SonareModule {
     stftBlendWeight: number,
     stftBlendNFft: number,
   ) => WasmNnlsChromaResult;
+  nnlsChromaEx: (
+    samples: Float32Array,
+    sampleRate: number,
+    enableStftBlend: boolean,
+    stftBlendWeight: number,
+    stftBlendNFft: number,
+    hopLength: number,
+  ) => WasmNnlsChromaResult;
   cqt: (
     samples: Float32Array,
     sampleRate: number,

package/src/stream_analyzer.ts

@@ -1,3 +1,4 @@
+import { resolveOrdinalInRange } from './codes';
 import { getSonareModule } from './module_state';
 import type { ChordQuality, PitchClass } from './public_types';
 import type { WasmStreamAnalyzer } from './sonare.js';
@@ -73,6 +74,10 @@ export class StreamAnalyzer {
     ) {
       throw new TypeError('outputFormat must be the integer 0 (Float32)');
     }
+    const window =
+      config.window === undefined
+        ? undefined
+        : resolveOrdinalInRange(config.window, 0, 3, 'stream analyzer window');
     const module = getSonareModule();
     const defaults = streamAnalyzerConfigDefaults();
     this.analyzer = new module.StreamAnalyzer(
@@ -94,7 +99,7 @@ export class StreamAnalyzer {
       config.maxProgressionEntries ?? defaults.maxProgressionEntries,
       config.keyUpdateIntervalSec ?? defaults.keyUpdateIntervalSec,
       config.bpmUpdateIntervalSec ?? defaults.bpmUpdateIntervalSec,
-      config.window ?? defaults.window,
+      window ?? defaults.window,
       config.outputFormat ?? defaults.outputFormat,
     );
   }

package/src/web_midi.ts

@@ -214,6 +214,10 @@ export async function bindWebMidi(
     bound.delete(input.id);
   };
 
+  // Does not call notify() itself: both call sites below (the initial sync
+  // and stateListener's fallback branch) already notify exactly once after
+  // calling this, so notifying here too would fire onInputsChanged twice per
+  // hotplug event that goes through the fallback branch.
   const refreshInputs = () => {
     for (const [, entry] of bound) {
       if (!shouldBind(entry.input)) {
@@ -223,7 +227,6 @@ export async function bindWebMidi(
     for (const [, input] of iterInputs(access)) {
       bindInput(input);
     }
-    notify();
   };
 
   const stateListener = (event: MidiConnectionEventLike) => {
@@ -244,6 +247,7 @@ export async function bindWebMidi(
   };
 
   refreshInputs();
+  notify();
   if (access.addEventListener) {
     access.addEventListener('statechange', stateListener);
   } else {
@@ -368,12 +372,11 @@ function dispatchUmpMessage(
     if (status === 0x8) {
       engine.pushMidiInputNoteOff(group, channel, data1, (word1 >>> 25) & 0x7f, portTimeSamples);
     } else if (status === 0x9) {
-      const velocity = (word1 >>> 25) & 0x7f;
-      if (velocity === 0) {
-        engine.pushMidiInputNoteOff(group, channel, data1, 0, portTimeSamples);
-      } else {
-        engine.pushMidiInputNoteOn(group, channel, data1, velocity, portTimeSamples);
-      }
+      // MIDI 2.0 note-on is distinct from note-off (status 0x8). Downsample
+      // its 16-bit velocity to the engine's 7-bit API, retaining a nonzero
+      // note-on even when the top seven bits are all zero.
+      const velocity = Math.max(1, (word1 >>> 25) & 0x7f);
+      engine.pushMidiInputNoteOn(group, channel, data1, velocity, portTimeSamples);
     } else if (status === 0xb) {
       engine.pushMidiInputCc(group, channel, data1, (word1 >>> 25) & 0x7f, portTimeSamples);
     }

package/src/worklet/engine-node.ts

@@ -1,7 +1,9 @@
 import type { EngineCaptureStatus, EngineTransportState } from '../index';
 import { engineCapabilities } from '../index';
 import {
+  engineCaptureResponseRequestId,
   isClipPageRequestMessage,
+  isEngineCaptureResponseForOperation,
   isEngineCaptureResponseMessage,
   isEngineTelemetryRecord,
   isEngineTransportResponseMessage,
@@ -10,7 +12,7 @@ import {
 } from './guards';
 import type {
   SonareEngineCaptureRequestMessage,
-  SonareEngineCaptureResponseMessage,
+  SonareEngineCaptureResponseMessageInternal,
   SonareEngineClipPageRequestMessage,
   SonareEngineSyncErrorMessage,
   SonareEngineTransportResponseMessage,
@@ -53,12 +55,28 @@ function isFiniteInteger(value: number | bigint | undefined): boolean {
   return typeof value === 'bigint' || (Number.isFinite(value) && Number.isSafeInteger(value));
 }
 
+function isTrackMonitorMode(value: number | bigint | undefined): boolean {
+  if (value === undefined) {
+    return false;
+  }
+  const mode = typeof value === 'bigint' ? Number(value) : value;
+  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.SeekMarker &&
+      type !== SonareEngineCommandType.SetTrackMonitorMode)
   ) {
     return false;
   }
@@ -66,7 +84,9 @@ function isValidCommandRecord(command: SonareEngineCommandRecord): boolean {
     (command.targetId === undefined || Number.isSafeInteger(command.targetId)) &&
     (command.argFloat === undefined || Number.isFinite(command.argFloat)) &&
     isFiniteInteger(command.argInt) &&
-    isFiniteInteger(command.sampleTime)
+    isFiniteInteger(command.sampleTime) &&
+    (type !== SonareEngineCommandType.SetTrackMonitorMode ||
+      (isTrackMonitorLaneIndex(command.targetId) && isTrackMonitorMode(command.argInt)))
   );
 }
 
@@ -109,7 +129,8 @@ export class SonareRealtimeEngineNode {
   private readonly captureRequests = new Map<
     number,
     {
-      resolve: (response: SonareEngineCaptureResponseMessage) => void;
+      op: SonareEngineCaptureRequestMessage['op'];
+      resolve: (response: SonareEngineCaptureResponseMessageInternal) => void;
       reject: (reason?: unknown) => void;
     }
   >();
@@ -151,14 +172,19 @@ export class SonareRealtimeEngineNode {
       this.resolveReady();
     }
     this.node.port.onmessage = (event: MessageEvent<unknown>) => {
-      if (isEngineCaptureResponseMessage(event.data)) {
-        const pending = this.captureRequests.get(event.data.requestId);
+      const captureRequestId = engineCaptureResponseRequestId(event.data);
+      if (captureRequestId !== undefined) {
+        const pending = this.captureRequests.get(captureRequestId);
         if (pending) {
-          this.captureRequests.delete(event.data.requestId);
-          if (event.data.ok) {
+          this.captureRequests.delete(captureRequestId);
+          if (!isEngineCaptureResponseMessage(event.data)) {
+            pending.reject(new Error('Malformed capture response.'));
+          } else if (!isEngineCaptureResponseForOperation(event.data, pending.op)) {
+            pending.reject(new Error('Capture response does not match request operation.'));
+          } else if (event.data.ok) {
             pending.resolve(event.data);
           } else {
-            pending.reject(new Error(event.data.error ?? 'Capture request failed'));
+            pending.reject(new Error(event.data.error));
           }
         }
       } else if (isEngineTransportResponseMessage(event.data)) {
@@ -375,7 +401,7 @@ export class SonareRealtimeEngineNode {
 
   requestCaptureStatus(): Promise<EngineCaptureStatus> {
     return this.sendCaptureRequest('status').then((response) => {
-      if (!response.status) {
+      if (!response.ok || !('status' in response)) {
         throw new Error('Capture status response is missing status.');
       }
       return response.status;
@@ -383,11 +409,12 @@ export class SonareRealtimeEngineNode {
   }
 
   requestCapturedAudio(): Promise<Float32Array[]> {
-    return this.sendCaptureRequest('read').then((response) =>
-      (response.channels ?? []).map((channel) =>
-        channel instanceof Float32Array ? channel : new Float32Array(channel),
-      ),
-    );
+    return this.sendCaptureRequest('read').then((response) => {
+      if (!response.ok || !('channels' in response)) {
+        throw new Error('Capture read response is missing channels.');
+      }
+      return response.channels;
+    });
   }
 
   requestCaptureReset(): Promise<void> {
@@ -529,6 +556,7 @@ export class SonareRealtimeEngineNode {
     this.startRingPolling();
     return () => {
       this.midiOutListeners.delete(callback);
+      this.stopRingPollingIfUnused();
     };
   }
 
@@ -633,15 +661,22 @@ export class SonareRealtimeEngineNode {
 
   private sendCaptureRequest(
     op: SonareEngineCaptureRequestMessage['op'],
-  ): Promise<SonareEngineCaptureResponseMessage> {
+  ): Promise<SonareEngineCaptureResponseMessageInternal> {
     if (this.destroyed) {
       return Promise.reject(new Error('Realtime engine node is destroyed.'));
     }
     const requestId = this.captureRequestId++;
-    const promise = new Promise<SonareEngineCaptureResponseMessage>((resolve, reject) => {
-      this.captureRequests.set(requestId, { resolve, reject });
+    let rejectRequest!: (reason?: unknown) => void;
+    const promise = new Promise<SonareEngineCaptureResponseMessageInternal>((resolve, reject) => {
+      rejectRequest = reject;
+      this.captureRequests.set(requestId, { op, resolve, reject });
     });
-    this.node.port.postMessage({ type: 'captureRequest', requestId, op });
+    try {
+      this.node.port.postMessage({ type: 'captureRequest', requestId, op });
+    } catch (error) {
+      this.captureRequests.delete(requestId);
+      rejectRequest(error);
+    }
     return promise;
   }
 

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

@@ -1,4 +1,10 @@
-import type { EngineAutomationPoint, EngineParameterInfo, RealtimeEngine } from '../index';
+import { trackMonitorModeCode } from '../codes';
+import type {
+  EngineAutomationPoint,
+  EngineParameterInfo,
+  EngineTrackMonitorMode,
+  RealtimeEngine,
+} from '../index';
 import type { SonareEngineSyncMessage } from './messages';
 import {
   ENGINE_MIXER_PARAM_FADER_DB,
@@ -67,6 +73,29 @@ export function setSoloMute(
   });
 }
 
+export function setTrackMonitorMode(
+  ctx: EngineParameterContext,
+  target: string | number,
+  mode: EngineTrackMonitorMode,
+  renderFrame = -1,
+): boolean {
+  // Resolve the mode before declaring a lane or touching either engine. This
+  // keeps booleans, fractions, and unknown spellings from reaching the queue.
+  const modeOrdinal = trackMonitorModeCode(mode);
+  const laneIndex = ctx.ensureTrackLane(target);
+  ctx.offlineEngine.setTrackMonitorMode(
+    laneIndex,
+    modeOrdinal as EngineTrackMonitorMode,
+    renderFrame,
+  );
+  return ctx.sendCommand({
+    type: SonareEngineCommandType.SetTrackMonitorMode,
+    targetId: laneIndex,
+    sampleTime: renderFrame,
+    argInt: modeOrdinal,
+  });
+}
+
 /**
  * Returns the automation target id for a mixer strip parameter.
  *

package/src/worklet/engine-processor.ts

@@ -6,7 +6,7 @@ import {
   type ResolvedMetronomeConfig,
   resolveMetronomeConfig,
   type SonareEngineCaptureRequestMessage,
-  type SonareEngineCaptureResponseMessage,
+  type SonareEngineCaptureResponseMessageInternal,
   type SonareEngineSyncMessage,
   type SonareEngineTransportRequestMessage,
   type SonareEngineTransportResponseMessage,
@@ -46,6 +46,22 @@ import {
   writeSonareEngineTelemetryRingBuffer,
 } from './protocol';
 
+function captureTransferList(channels: readonly Float32Array[]): Transferable[] {
+  const transfers: ArrayBuffer[] = [];
+  const seen = new Set<ArrayBuffer>();
+  for (const channel of channels) {
+    const buffer = channel.buffer;
+    if (!(buffer instanceof ArrayBuffer)) {
+      throw new TypeError('capture response channels must use plain ArrayBuffers');
+    }
+    if (!seen.has(buffer)) {
+      seen.add(buffer);
+      transfers.push(buffer);
+    }
+  }
+  return transfers;
+}
+
 /**
  * AudioWorklet-style bridge for the DAW realtime engine facade.
  *
@@ -599,26 +615,24 @@ export class SonareRealtimeEngineWorkletProcessor {
             source: status.source,
             recordOffsetSamples: status.recordOffsetSamples,
           },
-        } satisfies SonareEngineCaptureResponseMessage);
+        } satisfies SonareEngineCaptureResponseMessageInternal);
         return;
       }
       if (message.op === 'read') {
-        const captured = this.engine.capturedAudio();
-        const channels: number[][] = [];
-        for (let ch = 0; ch < captured.length; ch++) {
-          const source = captured[ch];
-          const copy: number[] = [];
-          for (let i = 0; i < source.length; i++) {
-            copy.push(Number(source[i]));
-          }
-          channels.push(copy);
-        }
-        this.transport?.postMessage?.({
-          type: 'captureResponse',
-          requestId: message.requestId,
-          ok: true,
-          channels,
-        } satisfies SonareEngineCaptureResponseMessage);
+        // Embind's outer val::array is array-like but not structured-cloneable
+        // in every host. Copy only that tiny container; keep each native
+        // Float32Array intact so the channel payload remains transferable.
+        const channels = Array.from(this.engine.capturedAudio());
+        const transfer = captureTransferList(channels);
+        this.transport?.postMessage?.(
+          {
+            type: 'captureResponse',
+            requestId: message.requestId,
+            ok: true,
+            channels,
+          } satisfies SonareEngineCaptureResponseMessageInternal,
+          transfer,
+        );
         return;
       }
       this.engine.resetCapture();
@@ -626,14 +640,14 @@ export class SonareRealtimeEngineWorkletProcessor {
         type: 'captureResponse',
         requestId: message.requestId,
         ok: true,
-      } satisfies SonareEngineCaptureResponseMessage);
+      } satisfies SonareEngineCaptureResponseMessageInternal);
     } catch (error) {
       this.transport?.postMessage?.({
         type: 'captureResponse',
         requestId: message.requestId,
         ok: false,
         error: error instanceof Error ? error.message : String(error),
-      } satisfies SonareEngineCaptureResponseMessage);
+      } satisfies SonareEngineCaptureResponseMessageInternal);
     }
   }
 
@@ -773,6 +787,24 @@ export class SonareRealtimeEngineWorkletProcessor {
           sampleTime,
         );
         break;
+      case SonareEngineCommandType.SetTrackMonitorMode: {
+        const rawMode = command.argInt;
+        const mode = typeof rawMode === 'bigint' ? Number(rawMode) : rawMode;
+        if (typeof mode !== 'number' || !Number.isSafeInteger(mode) || mode < 0 || mode > 2) {
+          throw new RangeError(`Invalid track monitor mode: ${String(rawMode)}`);
+        }
+        const laneIndex = command.targetId;
+        if (
+          typeof laneIndex !== 'number' ||
+          !Number.isSafeInteger(laneIndex) ||
+          laneIndex < 0 ||
+          laneIndex > 0xffff_ffff
+        ) {
+          throw new RangeError(`Invalid track monitor lane index: ${String(laneIndex)}`);
+        }
+        this.engine.setTrackMonitorMode(laneIndex, mode as 0 | 1 | 2, sampleTime);
+        break;
+      }
       default:
         this.publishTelemetryRecord({
           type: SonareEngineTelemetryType.Error,

package/src/worklet/engine-register.ts

@@ -121,7 +121,7 @@ export function registerSonareRealtimeEngineWorkletProcessor(
           throw new Error('AudioWorklet initialization message buffer overflowed.');
         }
         this.bridge = new SonareRealtimeEngineWorkletProcessor(options, {
-          postMessage: (message) => port?.postMessage?.(message),
+          postMessage: (message, transfer) => port?.postMessage?.(message, transfer),
           onMeter: (meter) => port?.postMessage?.(meter),
         });
         for (const message of options.initialSyncMessages ?? []) {

package/src/worklet/engine-strips.ts

@@ -1,5 +1,5 @@
 import { panLawCode, panModeCode } from '../codes';
-import type { EqBand, PanLaw, PanMode, RealtimeEngine } from '../index';
+import type { EqBand, PanLawInput, PanMode, RealtimeEngine } from '../index';
 import type { SonareEngineInstrumentSyncMessage, SonareEngineSyncMessage } from './messages';
 
 /**
@@ -85,7 +85,7 @@ export function setTrackStripPan(
 export function setTrackStripPanLaw(
   ctx: EngineStripContext,
   target: string | number,
-  panLaw: PanLaw | number,
+  panLaw: PanLawInput,
 ): void {
   const trackId = trackIdFor(ctx, target);
   const code = panLawCode(panLaw);

package/src/worklet/engine.ts

@@ -15,6 +15,7 @@ import type {
   EngineTempoSegment,
   EngineTimeSignatureSegment,
   EngineTrackLane,
+  EngineTrackMonitorMode,
   EngineTrackSend,
   EngineTransportState,
   EqBand,
@@ -386,6 +387,15 @@ export class SonareEngine {
     return parameter.setSoloMute(this.parameterContext, target, solo, mute);
   }
 
+  /** Queues a per-track PFL/AFL monitor tap mode change. */
+  setTrackMonitorMode(
+    target: string | number,
+    mode: EngineTrackMonitorMode,
+    renderFrame = -1,
+  ): boolean {
+    return parameter.setTrackMonitorMode(this.parameterContext, target, mode, renderFrame);
+  }
+
   setStripGain(target: string | number, db: number): boolean {
     return this.sendSmoothedParam(this.stripParamId(target, ENGINE_MIXER_PARAM_FADER_DB), db);
   }