@libraz/libsonare 1.2.2 → 1.2.3

package/src/worklet.ts

@@ -46,6 +46,8 @@ export interface SonareRealtimeEngineWorkletProcessorOptions {
   commandRingCapacity?: number;
   telemetrySharedBuffer?: SharedArrayBuffer;
   telemetryRingCapacity?: number;
+  meterSharedBuffer?: SharedArrayBuffer;
+  meterRingCapacity?: number;
 }
 
 export interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
@@ -182,8 +184,33 @@ export type SonareWorkletTransportMessage =
   | SonareEngineTelemetryRecord;
 
 export const SONARE_METER_RING_HEADER_INTS = 4;
-export const SONARE_METER_RING_RECORD_FLOATS = 6;
+// Record layout: [frameLo, peakDbL, peakDbR, rmsDbL, rmsDbR, correlation, frameHi].
+// The sample-frame index is monotonically increasing and quickly exceeds the
+// 2^24 exact-integer range of a single Float32 slot (~349 s at 48 kHz), so it is
+// stored split across two Float32 lanes (low 24 bits + high bits) for exact
+// reconstruction. See encodeFrameLo/encodeFrameHi/decodeFrame.
+export const SONARE_METER_RING_RECORD_FLOATS = 7;
 export const SONARE_SPECTRUM_RING_HEADER_INTS = 5;
+
+/** Base for splitting a frame index into two exactly-representable Float32 lanes. */
+const SONARE_FRAME_LANE_BASE = 0x1000000; // 2^24
+
+/** Low 24 bits of a frame index (exact in Float32). */
+export function encodeFrameLo(frame: number): number {
+  const f = Math.max(0, Math.floor(frame));
+  return f % SONARE_FRAME_LANE_BASE;
+}
+
+/** High bits of a frame index above 2^24 (exact in Float32 up to ~2^48). */
+export function encodeFrameHi(frame: number): number {
+  const f = Math.max(0, Math.floor(frame));
+  return Math.floor(f / SONARE_FRAME_LANE_BASE);
+}
+
+/** Reconstruct a frame index from its low/high Float32 lanes. */
+export function decodeFrame(lo: number, hi: number): number {
+  return hi * SONARE_FRAME_LANE_BASE + lo;
+}
 export const SONARE_ENGINE_RING_HEADER_INTS = 5;
 export const SONARE_ENGINE_COMMAND_RECORD_BYTES = 32;
 export const SONARE_ENGINE_TELEMETRY_RECORD_BYTES = 48;
@@ -237,6 +264,29 @@ interface WorkletTransport {
   onSpectrum?: (spectrum: SonareWorkletSpectrumSnapshot) => void;
 }
 
+interface ResolvedMetronomeConfig {
+  beatGain: number;
+  accentGain: number;
+  clickSamples: number;
+}
+
+// Fallback metronome gains/click length used by the worklet consumer until the
+// host posts a 'syncMetronome' config. Aligned with the embind setMetronome
+// defaults (src/wasm/bindings.cpp) so offline and realtime metronomes match.
+const DEFAULT_METRONOME_CONFIG: ResolvedMetronomeConfig = {
+  beatGain: 0.35,
+  accentGain: 0.7,
+  clickSamples: 96,
+};
+
+function resolveMetronomeConfig(config: EngineMetronomeConfig): ResolvedMetronomeConfig {
+  return {
+    beatGain: config.beatGain ?? DEFAULT_METRONOME_CONFIG.beatGain,
+    accentGain: config.accentGain ?? DEFAULT_METRONOME_CONFIG.accentGain,
+    clickSamples: config.clickSamples ?? DEFAULT_METRONOME_CONFIG.clickSamples,
+  };
+}
+
 export interface SonareMeterRingBuffer {
   sharedBuffer: SharedArrayBuffer;
   header: Int32Array;
@@ -270,6 +320,39 @@ export interface SonareEngineCommandRecord {
   argInt?: number | bigint;
 }
 
+// Out-of-band control messages posted from the main-thread SonareEngine facade
+// to the worklet engine processor over node.port. Unlike SonareEngineCommandRecord
+// (a small POD POSTed/ringed every block) these carry bulk/structured payloads
+// (clip audio buffers, marker lists, metronome config) that cannot fit the
+// fixed-size SAB command record, so they are applied OUTSIDE process() — the
+// audio-thread equivalent of the engine's control-thread RtPublisher setters.
+export interface SonareEngineSyncClipsMessage {
+  type: 'syncClips';
+  clips: EngineClip[];
+}
+
+export interface SonareEngineSyncMarkersMessage {
+  type: 'syncMarkers';
+  markers: EngineMarker[];
+}
+
+export interface SonareEngineSyncMetronomeMessage {
+  type: 'syncMetronome';
+  config: EngineMetronomeConfig;
+}
+
+export interface SonareEngineSyncAutomationMessage {
+  type: 'syncAutomation';
+  paramId: number;
+  points: EngineAutomationPoint[];
+}
+
+export type SonareEngineSyncMessage =
+  | SonareEngineSyncClipsMessage
+  | SonareEngineSyncMarkersMessage
+  | SonareEngineSyncMetronomeMessage
+  | SonareEngineSyncAutomationMessage;
+
 export interface SonareEngineTelemetryRecord {
   type: SonareEngineTelemetryType | number;
   error: SonareEngineTelemetryError | number;
@@ -343,6 +426,18 @@ function isEngineCommandRecord(value: unknown): value is SonareEngineCommandReco
   return isRecord(value) && typeof value.type === 'number';
 }
 
+function isEngineSyncMessage(value: unknown): value is SonareEngineSyncMessage {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return false;
+  }
+  return (
+    value.type === 'syncClips' ||
+    value.type === 'syncMarkers' ||
+    value.type === 'syncMetronome' ||
+    value.type === 'syncAutomation'
+  );
+}
+
 function isRealtimeVoiceChangerMessage(value: unknown): value is SonareRealtimeVoiceChangerMessage {
   if (!isRecord(value) || typeof value.type !== 'string') {
     return false;
@@ -407,7 +502,7 @@ export function readSonareMeterRingBuffer(
     const offset = (index % ring.capacity) * SONARE_METER_RING_RECORD_FLOATS;
     meters.push({
       type: 'meter',
-      frame: ring.records[offset],
+      frame: decodeFrame(ring.records[offset], ring.records[offset + 6]),
       peakDbL: ring.records[offset + 1],
       peakDbR: ring.records[offset + 2],
       rmsDbL: ring.records[offset + 3],
@@ -421,9 +516,11 @@ export function readSonareMeterRingBuffer(
 export function sonareSpectrumRingBufferByteLength(capacity: number, bands = 16): number {
   const clampedCapacity = Math.max(1, Math.floor(capacity));
   const clampedBands = Math.max(1, Math.floor(bands));
+  // Record layout: [frameLo, frameHi, bandCount, band0, band1, ...]. frame is
+  // split across two Float32 lanes for exact reconstruction beyond 2^24.
   return (
     SONARE_SPECTRUM_RING_HEADER_INTS * Int32Array.BYTES_PER_ELEMENT +
-    clampedCapacity * (2 + clampedBands) * Float32Array.BYTES_PER_ELEMENT
+    clampedCapacity * (3 + clampedBands) * Float32Array.BYTES_PER_ELEMENT
   );
 }
 
@@ -456,7 +553,7 @@ export function readSonareSpectrumRingBuffer(
   readIndex = 0,
 ): SonareSpectrumRingReadResult {
   const writeIndex = Atomics.load(ring.header, 0);
-  const recordFloats = Atomics.load(ring.header, 2) || 2 + ring.bands;
+  const recordFloats = Atomics.load(ring.header, 2) || 3 + ring.bands;
   const bands = Atomics.load(ring.header, 3) || ring.bands;
   const nextReadIndex = Math.max(0, Math.min(readIndex, writeIndex));
   const firstReadable = Math.max(nextReadIndex, writeIndex - ring.capacity);
@@ -464,8 +561,12 @@ export function readSonareSpectrumRingBuffer(
   for (let index = firstReadable; index < writeIndex; index++) {
     const offset = (index % ring.capacity) * recordFloats;
     const values = new Float32Array(bands);
-    values.set(ring.records.subarray(offset + 2, offset + 2 + bands));
-    spectra.push({ type: 'spectrum', frame: ring.records[offset], bands: values });
+    values.set(ring.records.subarray(offset + 3, offset + 3 + bands));
+    spectra.push({
+      type: 'spectrum',
+      frame: decodeFrame(ring.records[offset], ring.records[offset + 1]),
+      bands: values,
+    });
   }
   return { nextReadIndex: writeIndex, spectra };
 }
@@ -620,7 +721,7 @@ function spectrumRingFromSharedBuffer(
   const existingBands = Atomics.load(header, 3);
   const capacity = Math.max(1, Math.floor(existingCapacity || fallbackCapacity || 1));
   const bands = Math.max(1, Math.floor(existingBands || fallbackBands || 16));
-  const recordFloats = 2 + bands;
+  const recordFloats = 3 + bands;
   const minBytes = sonareSpectrumRingBufferByteLength(capacity, bands);
   if (sharedBuffer.byteLength < minBytes) {
     throw new Error('spectrumSharedBuffer is too small for the requested ring capacity.');
@@ -681,8 +782,10 @@ function writeEngineCommandRecord(
   view.setUint32(offset, command.type, true);
   view.setUint32(offset + 4, command.targetId ?? 0, true);
   view.setBigInt64(offset + 8, toBigInt64(command.sampleTime, -1n), true);
-  view.setFloat32(offset + 16, command.argFloat ?? 0, true);
-  view.setUint32(offset + 20, 0, true);
+  // argFloat occupies a full 8-byte Float64 slot (replacing the old Float32 +
+  // 4-byte pad) so PPQ scalars carried here keep full double precision over the
+  // SAB transport, matching the engine's double-precision seek/loop contract.
+  view.setFloat64(offset + 16, command.argFloat ?? 0, true);
   view.setBigInt64(offset + 24, toBigInt64(command.argInt, 0n), true);
 }
 
@@ -691,7 +794,7 @@ function readEngineCommandRecord(view: DataView, offset: number): SonareEngineCo
     type: view.getUint32(offset, true),
     targetId: view.getUint32(offset + 4, true),
     sampleTime: Number(view.getBigInt64(offset + 8, true)),
-    argFloat: view.getFloat32(offset + 16, true),
+    argFloat: view.getFloat64(offset + 16, true),
     argInt: Number(view.getBigInt64(offset + 24, true)),
   };
 }
@@ -818,9 +921,14 @@ export class SonareWorkletProcessor {
       return true;
     }
     const frames = leftOut.length;
-    if (frames !== this.blockSize) {
-      return false;
-    }
+    // The mixer's realtime heap buffers are sized to blockSize. A render quantum
+    // that differs from blockSize (e.g. a future browser using a quantum other
+    // than 128, or a misconfigured blockSize) must NOT return false here:
+    // returning false permanently terminates the AudioWorkletProcessor and
+    // silently kills the node mid-stream. Instead degrade gracefully by
+    // processing min(frames, blockSize) and zero-filling any remainder, mirroring
+    // the sonare-rt processor's behaviour.
+    const usable = Math.min(frames, this.blockSize);
 
     for (let strip = 0; strip < this.realtime.leftInputs.length; strip++) {
       const input = inputs[strip];
@@ -828,12 +936,12 @@ export class SonareWorkletProcessor {
       const right = input?.[1];
       const leftTarget = this.realtime.leftInputs[strip];
       const rightTarget = this.realtime.rightInputs[strip];
-      if (left && left.length === frames) {
-        leftTarget.set(left);
-        if (right && right.length === frames) {
-          rightTarget.set(right);
+      if (left && left.length >= usable) {
+        leftTarget.set(left.subarray(0, usable));
+        if (right && right.length >= usable) {
+          rightTarget.set(right.subarray(0, usable));
         } else {
-          rightTarget.set(left);
+          rightTarget.set(left.subarray(0, usable));
         }
       } else {
         leftTarget.fill(0);
@@ -841,14 +949,30 @@ export class SonareWorkletProcessor {
       }
     }
 
-    this.realtime.process(frames);
-    leftOut.set(this.realtime.outLeft);
-    if (rightOut) {
-      rightOut.set(this.realtime.outRight);
+    this.realtime.process(usable);
+    if (usable === frames) {
+      leftOut.set(this.realtime.outLeft.subarray(0, usable));
+      if (rightOut) {
+        rightOut.set(this.realtime.outRight.subarray(0, usable));
+      }
+    } else {
+      // frames > blockSize: fill the produced part and zero the remaining tail.
+      leftOut.fill(0);
+      leftOut.set(this.realtime.outLeft.subarray(0, usable));
+      if (rightOut) {
+        rightOut.fill(0);
+        rightOut.set(this.realtime.outRight.subarray(0, usable));
+      }
     }
-    this.processedFrames += frames;
-    this.publishMeter(this.realtime.outLeft, this.realtime.outRight);
-    this.publishSpectrum(this.realtime.outLeft, this.realtime.outRight);
+    this.processedFrames += usable;
+    this.publishMeter(
+      this.realtime.outLeft.subarray(0, usable),
+      this.realtime.outRight.subarray(0, usable),
+    );
+    this.publishSpectrum(
+      this.realtime.outLeft.subarray(0, usable),
+      this.realtime.outRight.subarray(0, usable),
+    );
     return true;
   }
 
@@ -939,16 +1063,19 @@ export class SonareWorkletProcessor {
     }
     const writeIndex = Atomics.load(ring.header, 0);
     const offset = (writeIndex % ring.capacity) * SONARE_METER_RING_RECORD_FLOATS;
-    ring.records[offset] = meter.frame;
+    ring.records[offset] = encodeFrameLo(meter.frame);
     ring.records[offset + 1] = meter.peakDbL;
     ring.records[offset + 2] = meter.peakDbR;
     ring.records[offset + 3] = meter.rmsDbL;
     ring.records[offset + 4] = meter.rmsDbR;
     ring.records[offset + 5] = meter.correlation;
+    ring.records[offset + 6] = encodeFrameHi(meter.frame);
     Atomics.store(ring.header, 0, writeIndex + 1);
-    if (writeIndex + 1 > ring.capacity) {
-      Atomics.store(ring.header, 3, writeIndex + 1 - ring.capacity);
-    }
+    // 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.
   }
 
   private publishSpectrum(left: Float32Array, right: Float32Array): void {
@@ -974,8 +1101,20 @@ export class SonareWorkletProcessor {
   }
 
   private computeSpectrum(left: Float32Array, right: Float32Array): void {
+    // Coarse per-render-quantum band energy, NOT a full FFT analyzer: each band
+    // is a single-bin DFT (bin = band + 1) evaluated over the current block of n
+    // samples. Bins at or above the block Nyquist (band + 1 > floor(n / 2))
+    // alias, so the evaluated band count is clamped to floor(n / 2) and any
+    // higher bands are pinned to the silence floor. Bin resolution is therefore
+    // tied to the render quantum (typically 128 samples); treat the output as a
+    // rough spectral tilt, not a precise spectrum.
     const n = Math.max(1, Math.min(left.length, right.length));
+    const maxBand = Math.floor(n / 2);
     for (let band = 0; band < this.spectrumBands.length; band++) {
+      if (band >= maxBand) {
+        this.spectrumBands[band] = magnitudeToDb(0);
+        continue;
+      }
       const bin = band + 1;
       let real = 0;
       let imag = 0;
@@ -996,13 +1135,15 @@ export class SonareWorkletProcessor {
     }
     const writeIndex = Atomics.load(ring.header, 0);
     const offset = (writeIndex % ring.capacity) * ring.recordFloats;
-    ring.records[offset] = frame;
-    ring.records[offset + 1] = bands.length;
-    ring.records.set(bands.subarray(0, ring.bands), offset + 2);
+    ring.records[offset] = encodeFrameLo(frame);
+    ring.records[offset + 1] = encodeFrameHi(frame);
+    ring.records[offset + 2] = bands.length;
+    ring.records.set(bands.subarray(0, ring.bands), offset + 3);
     Atomics.store(ring.header, 0, writeIndex + 1);
-    if (writeIndex + 1 > ring.capacity) {
-      Atomics.store(ring.header, 4, writeIndex + 1 - ring.capacity);
-    }
+    // See writeMeterRing: header slot 4 (the spectrum-ring overflow slot) is
+    // left at its initial 0; readers detect silent overrun via the
+    // firstReadable = max(readIndex, writeIndex - capacity) clamp. (Slot 3 here
+    // holds the band count and is still written at ring creation.)
   }
 }
 
@@ -1023,17 +1164,21 @@ export class SonareRealtimeEngineWorkletProcessor {
   private closed = false;
   private commandRing?: SonareEngineCommandRingBuffer;
   private telemetryRing?: SonareEngineTelemetryRingBuffer;
+  private meterRing?: SharedMeterRingWriter;
   private transport?: WorkletTransport;
   private meterIntervalFrames: number;
   private lastMeterFrame = Number.NEGATIVE_INFINITY;
-  // Pre-allocated worst-case input scratch buffers. The main thread allocates
-  // these in the constructor; process() reuses them via subarray() so it never
-  // touches the V8 heap allocator (which would risk GC stalls on the audio
-  // thread). One scratch buffer per channel sized to blockSize.
-  private readonly channelScratch: Float32Array[];
-  // Reused array of subarray views passed to engine.process() each block.
-  // Pre-allocating this array avoids growing-array allocations from .push().
-  private readonly channelScratchViews: Float32Array[];
+  // Latest metronome gains/click length pushed via 'syncMetronome'. The
+  // SetMetronome command only toggles enabled state; the config arrives here.
+  private metronomeConfig: ResolvedMetronomeConfig = { ...DEFAULT_METRONOME_CONFIG };
+  // Zero-copy prepared realtime path: persistent per-channel views onto the
+  // engine's WASM-heap scratch (acquired once on the main thread via
+  // getChannelBuffer). process() writes the AudioWorklet input straight into
+  // these views, calls engine.processPrepared(frames) which runs the engine IN
+  // PLACE, then reads the same views back — no std::vector or JS Float32Array is
+  // allocated per render quantum (the old engine.process() round-tripped fresh
+  // arrays on both heaps every block, an RT-safety hazard).
+  private channelBuffers: Float32Array[];
 
   constructor(
     options: SonareRealtimeEngineWorkletProcessorOptions = {},
@@ -1059,13 +1204,16 @@ export class SonareRealtimeEngineWorkletProcessor {
           options.telemetryRingCapacity,
         )
       : undefined;
+    this.meterRing = options.meterSharedBuffer
+      ? meterRingFromSharedBuffer(options.meterSharedBuffer, options.meterRingCapacity)
+      : undefined;
     this.engine = new RealtimeEngine(this.sampleRate, this.blockSize);
-    // Worst-case allocation: channelCount full-blockSize Float32Arrays.
-    this.channelScratch = new Array(this.channelCount);
-    this.channelScratchViews = new Array(this.channelCount);
+    // Allocate persistent WASM-heap scratch (worst case: channelCount channels x
+    // blockSize frames) and acquire the per-channel heap views once.
+    this.engine.prepareChannels(this.channelCount, this.blockSize);
+    this.channelBuffers = new Array(this.channelCount);
     for (let ch = 0; ch < this.channelCount; ch++) {
-      this.channelScratch[ch] = new Float32Array(this.blockSize);
-      this.channelScratchViews[ch] = this.channelScratch[ch];
+      this.channelBuffers[ch] = this.engine.getChannelBuffer(ch, this.blockSize);
     }
   }
 
@@ -1093,39 +1241,51 @@ export class SonareRealtimeEngineWorkletProcessor {
     // `frames > this.blockSize` branch already returns early, so this is
     // defensive — but we warn once if it ever fires so the contract violation
     // is visible.
-    const scratchCapacity = this.channelScratch[0]?.length ?? 0;
     let usableFrames = frames;
-    if (usableFrames > scratchCapacity) {
+    if (usableFrames > this.blockSize) {
       if (!SonareRealtimeEngineWorkletProcessor.warnedChannelScratchOverflow) {
         SonareRealtimeEngineWorkletProcessor.warnedChannelScratchOverflow = true;
         // biome-ignore lint/suspicious/noConsole: realtime-safety diagnostic.
         console.warn(
           `SonareRealtimeEngineWorkletProcessor: requested ${usableFrames} frames ` +
-            `exceeds pre-allocated capacity ${scratchCapacity}; clamping.`,
+            `exceeds pre-allocated capacity ${this.blockSize}; clamping.`,
         );
       }
-      usableFrames = scratchCapacity;
+      usableFrames = this.blockSize;
     }
+
+    // Defend against WASM linear-memory growth detaching the cached heap views:
+    // if any view's backing ArrayBuffer has been detached (byteLength === 0),
+    // re-acquire all of them. This is a control-flow check (no allocation in the
+    // common case where memory did not grow).
+    if ((this.channelBuffers[0]?.byteLength ?? 0) === 0) {
+      this.reacquireChannelBuffers();
+    }
+
     const input = inputs[0];
-    // Reuse the scratch buffers via subarray() — these are views over the
-    // pre-allocated Float32Array storage and do not allocate on the heap.
+    // Write the AudioWorklet input straight into the engine's WASM-heap views;
+    // no per-block heap allocation.
     for (let ch = 0; ch < this.channelCount; ch++) {
-      const scratch = this.channelScratch[ch];
+      const dst = this.channelBuffers[ch];
       const source = input?.[ch];
       if (source && source.length === usableFrames) {
-        scratch.set(source, 0);
+        dst.set(source.subarray(0, usableFrames));
       } else {
-        scratch.fill(0, 0, usableFrames);
+        dst.fill(0, 0, usableFrames);
       }
-      this.channelScratchViews[ch] = scratch.subarray(0, usableFrames);
     }
 
-    const processed = this.engine.process(this.channelScratchViews);
+    // Run the engine in place over the prepared scratch (allocation-free).
+    this.engine.processPrepared(usableFrames);
+
     for (let ch = 0; ch < output.length; ch++) {
       const target = output[ch];
-      const source = processed[ch] ?? processed[0];
+      const source = this.channelBuffers[ch] ?? this.channelBuffers[0];
       if (source) {
-        target.set(source.subarray(0, target.length));
+        target.set(source.subarray(0, Math.min(target.length, usableFrames)));
+        if (target.length > usableFrames) {
+          target.fill(0, usableFrames);
+        }
       } else {
         target.fill(0);
       }
@@ -1135,12 +1295,44 @@ export class SonareRealtimeEngineWorkletProcessor {
     return true;
   }
 
+  private reacquireChannelBuffers(): void {
+    for (let ch = 0; ch < this.channelCount; ch++) {
+      this.channelBuffers[ch] = this.engine.getChannelBuffer(ch, this.blockSize);
+    }
+  }
+
   receiveCommand(command: SonareEngineCommandRecord): void {
     if (!this.closed) {
       this.applyCommand(command);
     }
   }
 
+  // Applies an out-of-band control-plane sync message. Runs on the AudioWorklet
+  // global scope but OUTSIDE process() (the message-port callback), so the
+  // bulk/allocating engine setters (setClips/setMarkers) are safe here — they
+  // never run on the realtime render path. This is the audio-thread equivalent
+  // of the engine's control-thread RtPublisher setters.
+  receiveSync(message: SonareEngineSyncMessage): void {
+    if (this.closed) {
+      return;
+    }
+    switch (message.type) {
+      case 'syncClips':
+        this.engine.setClips(message.clips);
+        break;
+      case 'syncMarkers':
+        this.engine.setMarkers(message.markers);
+        break;
+      case 'syncMetronome':
+        this.metronomeConfig = resolveMetronomeConfig(message.config);
+        this.engine.setMetronome(message.config);
+        break;
+      case 'syncAutomation':
+        this.engine.setAutomationLane(message.paramId, message.points);
+        break;
+    }
+  }
+
   destroy(): void {
     if (!this.closed) {
       this.engine.destroy();
@@ -1164,6 +1356,22 @@ export class SonareRealtimeEngineWorkletProcessor {
   private applyCommand(command: SonareEngineCommandRecord): void {
     const sampleTime = Number(command.sampleTime ?? -1);
     switch (command.type) {
+      case SonareEngineCommandType.SetParam:
+        // paramId is carried in targetId, the new value in argFloat (matches the
+        // SonareEngine.setParam producer). sampleTime is the render frame.
+        this.engine.setParameter(
+          Math.trunc(Number(command.targetId ?? 0)),
+          Number(command.argFloat ?? 0),
+          sampleTime,
+        );
+        break;
+      case SonareEngineCommandType.SetParamSmoothed:
+        this.engine.setParameterSmoothed(
+          Math.trunc(Number(command.targetId ?? 0)),
+          Number(command.argFloat ?? 0),
+          sampleTime,
+        );
+        break;
       case SonareEngineCommandType.TransportPlay:
         this.engine.play(sampleTime);
         break;
@@ -1190,20 +1398,31 @@ export class SonareRealtimeEngineWorkletProcessor {
         this.engine.armCapture(Boolean(command.argInt));
         break;
       case SonareEngineCommandType.Punch:
+        // Both endpoints already arrive as samples (see SonareEngine.punch);
+        // do NOT re-scale by sampleRate.
         this.engine.setCapturePunch(
           Number(command.argInt ?? 0),
-          Math.max(0, Math.round(Number(command.argFloat ?? 0) * this.sampleRate)),
+          Math.max(0, Math.round(Number(command.argFloat ?? 0))),
           true,
         );
         break;
       case SonareEngineCommandType.SetMetronome:
+        // Metronome config (beatGain/accentGain/clickSamples/clickSeconds) is
+        // delivered out-of-band via the 'syncMetronome' message so it carries
+        // the caller's full config; the command only toggles enabled state as a
+        // sample-aligned fallback.
         this.engine.setMetronome({
           enabled: Boolean(command.argInt),
-          beatGain: 0.25,
-          accentGain: 0.75,
-          clickSamples: 64,
+          beatGain: this.metronomeConfig.beatGain,
+          accentGain: this.metronomeConfig.accentGain,
+          clickSamples: this.metronomeConfig.clickSamples,
         });
         break;
+      case SonareEngineCommandType.SeekMarker:
+        // The realtime engine's markers are kept in sync via 'syncMarkers'
+        // (RtPublisher-style swap), so a queued kSeekMarker resolves correctly.
+        this.engine.seekMarker(Math.trunc(Number(command.targetId ?? 0)), sampleTime);
+        break;
       default:
         this.publishTelemetryRecord({
           type: SonareEngineTelemetryType.Error,
@@ -1233,7 +1452,7 @@ export class SonareRealtimeEngineWorkletProcessor {
   }
 
   private publishMeters(): void {
-    if (!this.transport || this.meterIntervalFrames <= 0) {
+    if (this.meterIntervalFrames <= 0 || (!this.transport && !this.meterRing)) {
       return;
     }
     for (const item of this.engine.drainMeterTelemetry(64)) {
@@ -1242,9 +1461,39 @@ export class SonareRealtimeEngineWorkletProcessor {
         continue;
       }
       this.lastMeterFrame = meter.frame;
-      this.transport.onMeter?.(meter);
-      this.transport.postMessage?.(meter);
+      // 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);
+      } else {
+        this.transport?.onMeter?.(meter);
+        this.transport?.postMessage?.(meter);
+      }
+    }
+  }
+
+  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] = meter.peakDbL;
+    ring.records[offset + 2] = meter.peakDbR;
+    ring.records[offset + 3] = meter.rmsDbL;
+    ring.records[offset + 4] = meter.rmsDbR;
+    ring.records[offset + 5] = meter.correlation;
+    ring.records[offset + 6] = encodeFrameHi(meter.frame);
+    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.
   }
 
   private commandRingFromSharedBuffer(
@@ -1285,6 +1534,7 @@ export class SonareRtRealtimeEngineRuntime {
   private readonly telemetryFramesPtr: number;
   private readonly commandRing?: SonareEngineCommandRingBuffer;
   private readonly telemetryRing?: SonareEngineTelemetryRingBuffer;
+  private metronomeConfig: ResolvedMetronomeConfig = { ...DEFAULT_METRONOME_CONFIG };
   private closed = false;
 
   constructor(options: SonareRtRealtimeEngineRuntimeOptions) {
@@ -1380,6 +1630,54 @@ export class SonareRtRealtimeEngineRuntime {
     return true;
   }
 
+  receiveCommand(command: SonareEngineCommandRecord): void {
+    if (!this.closed) {
+      this.applyCommand(command);
+    }
+  }
+
+  // Out-of-band control sync for the sonare-rt runtime. The sonare-rt C ABI
+  // (src/wasm/rt_bindings.cpp) exposes set_metronome_enabled and seek_marker but
+  // NOT set_clips / set_markers, so clip/marker mutations cannot be applied to a
+  // live sonare-rt engine. We honor the metronome config and surface a clear
+  // telemetry error for the unsupported clip/marker paths instead of silently
+  // dropping them. The default 'embind' runtime wires all three fully.
+  receiveSync(message: SonareEngineSyncMessage): void {
+    if (this.closed) {
+      return;
+    }
+    switch (message.type) {
+      case 'syncMetronome':
+        this.metronomeConfig = resolveMetronomeConfig(message.config);
+        this.module._sonare_rt_engine_set_metronome_enabled(
+          this.engine,
+          message.config.enabled ? 1 : 0,
+          this.metronomeConfig.beatGain,
+          this.metronomeConfig.accentGain,
+          this.metronomeConfig.clickSamples,
+        );
+        break;
+      case 'syncClips':
+      case 'syncMarkers':
+      case 'syncAutomation':
+        // The sonare-rt C ABI exposes no set_clips / set_markers /
+        // set_automation_lane, so these mutations cannot reach a live sonare-rt
+        // engine. Surface a clear telemetry error rather than silently dropping.
+        if (this.telemetryRing) {
+          writeSonareEngineTelemetryRingBuffer(this.telemetryRing, {
+            type: SonareEngineTelemetryType.Error,
+            error: SonareEngineTelemetryError.UnknownTarget,
+            renderFrame: 0,
+            timelineSample: 0,
+            audibleTimelineSample: 0,
+            graphLatencySamplesQ8: 0,
+            value: 0,
+          });
+        }
+        break;
+    }
+  }
+
   destroy(): void {
     if (this.closed) {
       return;
@@ -1418,6 +1716,25 @@ export class SonareRtRealtimeEngineRuntime {
   private applyCommand(command: SonareEngineCommandRecord): void {
     const sampleTime = toBigInt64(command.sampleTime, -1n);
     switch (command.type) {
+      case SonareEngineCommandType.SetParam:
+      case SonareEngineCommandType.SetParamSmoothed:
+        // The sonare-rt C ABI (src/wasm/rt_bindings.cpp) does not export a
+        // sonare_rt_engine_set_param entry point, so parameter automation has no
+        // realtime transport on this runtime target. Surface a clear error
+        // telemetry record (rather than silently dropping the command) so hosts
+        // can detect the unsupported path; the embind runtime fully wires this.
+        if (this.telemetryRing) {
+          writeSonareEngineTelemetryRingBuffer(this.telemetryRing, {
+            type: SonareEngineTelemetryType.Error,
+            error: SonareEngineTelemetryError.UnknownTarget,
+            renderFrame: 0,
+            timelineSample: 0,
+            audibleTimelineSample: 0,
+            graphLatencySamplesQ8: 0,
+            value: Number(command.type),
+          });
+        }
+        break;
       case SonareEngineCommandType.TransportPlay:
         this.module._sonare_rt_engine_play(this.engine, sampleTime);
         break;
@@ -1453,10 +1770,12 @@ export class SonareRtRealtimeEngineRuntime {
         this.module._sonare_rt_engine_set_capture_armed(this.engine, command.argInt ? 1 : 0);
         break;
       case SonareEngineCommandType.Punch:
+        // Both endpoints already arrive as samples (see SonareEngine.punch);
+        // do NOT re-scale by sampleRate.
         this.module._sonare_rt_engine_set_capture_punch(
           this.engine,
           toBigInt64(command.argInt, 0n),
-          BigInt(Math.trunc(Number(command.argFloat ?? 0) * this.sampleRate)),
+          BigInt(Math.max(0, Math.round(Number(command.argFloat ?? 0)))),
           1,
         );
         break;
@@ -1464,9 +1783,9 @@ export class SonareRtRealtimeEngineRuntime {
         this.module._sonare_rt_engine_set_metronome_enabled(
           this.engine,
           command.argInt ? 1 : 0,
-          0.25,
-          0.75,
-          64,
+          this.metronomeConfig.beatGain,
+          this.metronomeConfig.accentGain,
+          this.metronomeConfig.clickSamples,
         );
         break;
       case SonareEngineCommandType.SeekMarker:
@@ -1555,8 +1874,10 @@ export class SonareRealtimeEngineNode {
   readonly capabilities: SonareRealtimeEngineNodeCapabilities;
   readonly commandRing?: SonareEngineCommandRingBuffer;
   readonly telemetryRing?: SonareEngineTelemetryRingBuffer;
+  readonly meterRing?: SonareMeterRingBuffer;
   readonly ready: Promise<void>;
   private telemetryReadIndex = 0;
+  private meterReadIndex = 0;
   private telemetryListeners = new Set<(telemetry: SonareEngineTelemetryRecord) => void>();
   private meterListeners = new Set<(meter: SonareWorkletMeterSnapshot) => void>();
   private resolveReady!: () => void;
@@ -1568,11 +1889,13 @@ export class SonareRealtimeEngineNode {
     capabilities: SonareRealtimeEngineNodeCapabilities,
     commandRing?: SonareEngineCommandRingBuffer,
     telemetryRing?: SonareEngineTelemetryRingBuffer,
+    meterRing?: SonareMeterRingBuffer,
   ) {
     this.node = node;
     this.capabilities = capabilities;
     this.commandRing = commandRing;
     this.telemetryRing = telemetryRing;
+    this.meterRing = meterRing;
     this.ready = new Promise((resolve, reject) => {
       this.resolveReady = resolve;
       this.rejectReady = reject;
@@ -1643,6 +1966,14 @@ export class SonareRealtimeEngineNode {
       mode === 'sab'
         ? createSonareEngineTelemetryRingBuffer(options.telemetryRingCapacity ?? 128)
         : undefined;
+    // Meter ring: only the embind runtime publishes engine meters into a SAB
+    // ring (the sonare-rt runtime owns its own meter transport). Lock-free
+    // meter delivery matches the telemetry path and keeps the audio render
+    // callback allocation-free in SAB mode.
+    const meterRing =
+      mode === 'sab' && runtimeTarget === 'embind'
+        ? createSonareMeterRingBuffer(options.meterRingCapacity ?? 128)
+        : undefined;
     const channelCount = Math.max(1, Math.floor(options.channelCount ?? 2));
     const processorOptions: SonareRealtimeEngineWorkletProcessorOptions = {
       runtimeTarget,
@@ -1655,6 +1986,8 @@ export class SonareRealtimeEngineNode {
       commandRingCapacity: commandRing?.capacity,
       telemetrySharedBuffer: telemetryRing?.sharedBuffer,
       telemetryRingCapacity: telemetryRing?.capacity,
+      meterSharedBuffer: meterRing?.sharedBuffer,
+      meterRingCapacity: meterRing?.capacity,
     };
     const factory =
       options.nodeFactory ??
@@ -1681,6 +2014,7 @@ export class SonareRealtimeEngineNode {
       },
       commandRing,
       telemetryRing,
+      meterRing,
     );
   }
 
@@ -1731,6 +2065,21 @@ export class SonareRealtimeEngineNode {
     return read.telemetry;
   }
 
+  // Drains any meters published into the SAB meter ring (embind SAB mode) and
+  // forwards them to onMeter listeners. In postMessage mode meters arrive via
+  // node.port.onmessage instead, so this is a no-op then.
+  pollMeters(): SonareWorkletMeterSnapshot[] {
+    if (!this.meterRing) {
+      return [];
+    }
+    const read = readSonareMeterRingBuffer(this.meterRing, this.meterReadIndex);
+    this.meterReadIndex = read.nextReadIndex;
+    for (const meter of read.meters) {
+      this.emitMeter(meter);
+    }
+    return read.meters;
+  }
+
   onTelemetry(callback: (telemetry: SonareEngineTelemetryRecord) => void): () => void {
     this.telemetryListeners.add(callback);
     return () => {
@@ -1866,6 +2215,15 @@ export class SonareEngine {
 
   setLoop(startPpq: number, endPpq: number, enabled = true): boolean {
     this.offlineEngine.setLoop(startPpq, endPpq, enabled);
+    // Transport precision contract: the SAB command record carries exactly one
+    // Float64 lane (argFloat) and one Int64 lane (argInt). startPpq travels in
+    // argFloat with full double precision, matching the offline engine; endPpq
+    // is carried as micro-PPQ (round(endPpq * 1e6)) in the integer lane and
+    // divided back by 1e6 on the consumer. Loop ENDS are therefore snapped to
+    // the nearest 1e-6 PPQ over the realtime transport (max 5e-7 PPQ drift),
+    // while loop STARTS and the offline path stay exact. This is intentional:
+    // the record has no second free Float64 lane, and a micro-PPQ grid on the
+    // loop end is well below audible/sample-accurate resolution at any tempo.
     return this.realtimeNode.sendCommand({
       type: SonareEngineCommandType.SetLoop,
       targetId: enabled ? 1 : 0,
@@ -1876,10 +2234,17 @@ export class SonareEngine {
   }
 
   setParam(nodeId: string, param: string | number, value: number): boolean {
-    void nodeId;
-    void param;
-    void value;
-    return false;
+    const paramId = this.resolveParamId(nodeId, param);
+    // Mirror the change into the offline engine so a subsequent offline render
+    // reflects the live value, then push a sample-accurate command to the
+    // realtime runtime (mirrors setTempo/setLoop above).
+    this.offlineEngine.setParameter(paramId, value);
+    return this.realtimeNode.sendCommand({
+      type: SonareEngineCommandType.SetParam,
+      targetId: paramId,
+      sampleTime: -1,
+      argFloat: value,
+    });
   }
 
   scheduleParam(
@@ -1895,6 +2260,11 @@ export class SonareEngine {
     lane.sort((a, b) => a.ppq - b.ppq);
     this.automationLanes.set(paramId, lane);
     this.offlineEngine.setAutomationLane(paramId, lane);
+    // Mirror the lane to the live worklet engine so scheduled automation plays
+    // back in real time, not just in renderOffline(). Lanes can exceed the
+    // fixed-size SAB command record, so they ride an out-of-band 'syncAutomation'
+    // message applied outside process() (like syncClips/syncMarkers).
+    this.postSync({ type: 'syncAutomation', paramId, points: lane });
   }
 
   addAutomationPoint(
@@ -1918,7 +2288,16 @@ export class SonareEngine {
     void target;
     void solo;
     void mute;
-    return false;
+    // Per-track solo/mute is a Mixer concept (strip-indexed setSoloed/setMuted),
+    // not an engine command: the WASM SonareEngine facade does not own a Mixer
+    // node, so there is no realtime transport for solo/mute on this surface.
+    // Throw a clear error instead of silently returning false (a silent no-op
+    // would leave callers believing the change took effect). Apply solo/mute
+    // directly on a Mixer instance (Mixer.setSoloed/Mixer.setMuted) instead.
+    throw new Error(
+      'SonareEngine.setSoloMute is not supported: solo/mute is a Mixer feature; ' +
+        'use Mixer.setSoloed(stripIndex, ...) / Mixer.setMuted(stripIndex, ...) instead.',
+    );
   }
 
   addClip(
@@ -1959,16 +2338,25 @@ export class SonareEngine {
     const inSample = this.ppqToApproxSample(inPpq);
     const outSample = this.ppqToApproxSample(outPpq);
     this.offlineEngine.setCapturePunch(inSample, outSample, true);
+    // Carry BOTH endpoints as already-converted SAMPLES so the realtime engine
+    // agrees with the offline engine. The previous code sent the raw PPQ out
+    // point and let the consumer multiply by sampleRate (treating PPQ as
+    // seconds), which ignored tempo and produced a punch-out ~2x too large at
+    // 120 BPM. argInt = in sample, argFloat = out sample (full-precision double).
     return this.realtimeNode.sendCommand({
       type: SonareEngineCommandType.Punch,
       sampleTime: -1,
       argInt: inSample,
-      argFloat: outPpq,
+      argFloat: outSample,
     });
   }
 
   setMetronome(opts: EngineMetronomeConfig): void {
     this.offlineEngine.setMetronome(opts);
+    // The full config (beatGain/accentGain/clickSamples/clickSeconds) cannot fit
+    // the fixed-size SAB command record, so it is delivered out-of-band; the
+    // SetMetronome command then toggles enabled state on the audio thread.
+    this.postSync({ type: 'syncMetronome', config: opts });
     this.realtimeNode.sendCommand({
       type: SonareEngineCommandType.SetMetronome,
       sampleTime: -1,
@@ -1985,7 +2373,15 @@ export class SonareEngine {
 
   seekMarker(markerId: number): boolean {
     this.offlineEngine.seekMarker(markerId);
-    return false;
+    // Forward to the live worklet engine. Its marker set is kept in sync via the
+    // 'syncMarkers' message (see syncMarkers), so a queued kSeekMarker resolves
+    // the marker id to its frame on the audio thread. Returns the sendCommand
+    // result (previously this method always returned a misleading `false`).
+    return this.realtimeNode.sendCommand({
+      type: SonareEngineCommandType.SeekMarker,
+      targetId: markerId,
+      sampleTime: -1,
+    });
   }
 
   async renderOffline(totalFrames: number): Promise<Float32Array[]> {
@@ -2009,6 +2405,10 @@ export class SonareEngine {
     return this.realtimeNode.pollTelemetry();
   }
 
+  pollMeters(): SonareWorkletMeterSnapshot[] {
+    return this.realtimeNode.pollMeters();
+  }
+
   destroy(): void {
     if (this.destroyed) {
       return;
@@ -2021,11 +2421,29 @@ export class SonareEngine {
   }
 
   private syncClips(): void {
-    this.offlineEngine.setClips(Array.from(this.clips.values()));
+    const clips = Array.from(this.clips.values());
+    this.offlineEngine.setClips(clips);
+    // Push the full clip set to the live worklet engine over the message port.
+    // Clip audio buffers are too large for the fixed-size SAB command record, so
+    // they ride a structured-clone 'syncClips' message applied OUTSIDE the audio
+    // render callback (the audio-thread equivalent of an RtPublisher swap).
+    this.postSync({ type: 'syncClips', clips });
   }
 
   private syncMarkers(): void {
-    this.offlineEngine.setMarkers(Array.from(this.markers.values()).sort((a, b) => a.ppq - b.ppq));
+    const markers = Array.from(this.markers.values()).sort((a, b) => a.ppq - b.ppq);
+    this.offlineEngine.setMarkers(markers);
+    this.postSync({ type: 'syncMarkers', markers });
+  }
+
+  // Posts an out-of-band control-sync message to the worklet engine processor.
+  // Sync messages use a string `type` so the worklet's message handler routes
+  // them to receiveSync() (numeric `type` is reserved for SonareEngineCommandRecord).
+  private postSync(message: SonareEngineSyncMessage): void {
+    if (this.destroyed) {
+      return;
+    }
+    this.realtimeNode.node.port.postMessage(message);
   }
 
   private resolveParamId(nodeId: string, param: string | number): number {
@@ -2127,6 +2545,14 @@ export class SonareRealtimeVoiceChangerWorkletProcessor {
       return !this.destroyed;
     }
 
+    // The cached heap views can detach if WASM linear memory grows (the embind
+    // module is built ALLOW_MEMORY_GROWTH). Re-acquire them if detached
+    // (byteLength === 0) before touching them; in the common no-growth case this
+    // is a cheap branch with no allocation.
+    if (this.monoInput.byteLength === 0) {
+      this.reacquireBuffers();
+    }
+
     const input = inputs[0];
     const requestedFrames = output[0]?.length ?? 0;
     const requestedChannels = Math.min(this.channelCount, output.length);
@@ -2188,6 +2614,20 @@ export class SonareRealtimeVoiceChangerWorkletProcessor {
     this.changer.delete();
   }
 
+  // Re-acquires the cached WASM-heap views after a memory-growth detachment.
+  // The underlying C++ vectors are pre-warmed (ensure_*_capacity ran at prepare
+  // time), so getMono*/getPlanar* return fresh views onto the SAME storage
+  // without reallocating it.
+  private reacquireBuffers(): void {
+    this.monoInput = this.changer.getMonoInputBuffer(this.blockSize);
+    this.monoOutput = this.changer.getMonoOutputBuffer(this.blockSize);
+    if (this.channelCount > 1) {
+      for (let ch = 0; ch < this.channelCount; ch++) {
+        this.planarChannels[ch] = this.changer.getPlanarChannelBuffer(ch, this.blockSize);
+      }
+    }
+  }
+
   /**
    * Returns the number of frames we can actually process given the
    * pre-allocated capacity. If the host requests more frames than the
@@ -2345,6 +2785,10 @@ export function registerSonareRealtimeEngineWorkletProcessor(
       const onMessage = (event: { data: unknown }) => {
         if (isEngineCommandRecord(event.data)) {
           this.bridge?.receiveCommand(event.data);
+          this.rtBridge?.receiveCommand(event.data);
+        } else if (isEngineSyncMessage(event.data)) {
+          this.bridge?.receiveSync(event.data);
+          this.rtBridge?.receiveSync(event.data);
         }
       };
       if (port?.addEventListener) {