@libraz/libsonare 1.4.1 → 1.5.1

package/src/worklet/guards.ts

@@ -5,6 +5,7 @@ import type {
   SonareEngineTransportRequestMessage,
   SonareEngineTransportResponseMessage,
   SonareRealtimeVoiceChangerMessage,
+  SonareWorkletExternalMidiMessage,
   SonareWorkletMessage,
 } from './messages';
 import {
@@ -49,6 +50,7 @@ export function isEngineSyncMessage(value: unknown): value is SonareEngineSyncMe
     value.type === 'syncMasterStripInsertBypassed' ||
     value.type === 'syncTrackStripInsertParamByName' ||
     value.type === 'syncMasterStripInsertParamByName' ||
+    value.type === 'syncBusStripInsertParamByName' ||
     value.type === 'syncTrackStripPan' ||
     value.type === 'syncTrackStripPanLaw' ||
     value.type === 'syncTrackStripPanMode' ||
@@ -58,10 +60,15 @@ export function isEngineSyncMessage(value: unknown): value is SonareEngineSyncMe
     value.type === 'syncSynthInstrument' ||
     value.type === 'syncSf2Instrument' ||
     value.type === 'syncLoadSoundFont' ||
+    value.type === 'syncMidiFx' ||
+    value.type === 'syncClearMidiFx' ||
     value.type === 'syncMidiNoteOn' ||
     value.type === 'syncMidiNoteOff' ||
     value.type === 'syncMidiCc' ||
-    value.type === 'syncMidiPanic'
+    value.type === 'syncMidiSysex' ||
+    value.type === 'syncMidiPanic' ||
+    value.type === 'syncMidiDestinationExternal' ||
+    value.type === 'syncExternalMidiClock'
   );
 }
 
@@ -131,6 +138,12 @@ export function isEngineTelemetryRecord(value: unknown): value is SonareEngineTe
   );
 }
 
+export function isExternalMidiBatchMessage(
+  value: unknown,
+): value is SonareWorkletExternalMidiMessage {
+  return isRecord(value) && value.type === 'externalMidi' && Array.isArray(value.events);
+}
+
 export function isMeterSnapshot(value: unknown): value is SonareWorkletMeterSnapshot {
   return (
     isRecord(value) &&

package/src/worklet/messages.ts

@@ -13,7 +13,6 @@ import type {
   RealtimeVoiceChangerConfigInput,
 } from '../index';
 import type { AutomationCurve } from '../public_types';
-import type { SonareRtModule } from '../sonare-rt';
 import type {
   SonareEngineCommandRecord,
   SonareEngineTelemetryRecord,
@@ -36,9 +35,6 @@ export interface SonareWorkletProcessorOptions {
 }
 
 export interface SonareRealtimeEngineWorkletProcessorOptions {
-  runtimeTarget?: 'embind' | 'sonare-rt';
-  rtModuleUrl?: string;
-  rtWasmBinary?: ArrayBuffer | Uint8Array;
   wasmBinary?: ArrayBuffer | Uint8Array;
   initialSyncMessages?: SonareEngineSyncMessage[];
   initialCommands?: SonareEngineCommandRecord[];
@@ -88,7 +84,7 @@ export type SonareRealtimeVoiceChangerMessage =
 
 export interface SonareRealtimeEngineNodeCapabilities {
   mode: 'sab' | 'postMessage';
-  runtimeTarget: 'embind' | 'sonare-rt';
+  runtimeTarget: 'embind';
   sharedArrayBuffer: boolean;
   atomics: boolean;
   audioWorklet: boolean;
@@ -103,7 +99,6 @@ export interface SonareRealtimeEngineNodeOptions
   extends SonareRealtimeEngineWorkletProcessorOptions {
   processorName?: string;
   moduleUrl?: string | URL;
-  rtModuleUrl?: string;
   mode?: 'auto' | 'sab' | 'postMessage';
   engineAbiVersion?: number;
   expectedEngineAbiVersion?: number;
@@ -115,18 +110,6 @@ export interface SonareRealtimeEngineNodeOptions
   ) => AudioWorkletNode;
 }
 
-export interface SonareRtRealtimeEngineRuntimeOptions {
-  module: SonareRtModule;
-  memory: WebAssembly.Memory;
-  sampleRate?: number;
-  blockSize?: number;
-  channelCount?: number;
-  commandSharedBuffer?: SharedArrayBuffer;
-  commandRingCapacity?: number;
-  telemetrySharedBuffer?: SharedArrayBuffer;
-  telemetryRingCapacity?: number;
-}
-
 export interface SonareEngineTransportFacade {
   play(sampleTime?: number): boolean;
   stop(sampleTime?: number): boolean;
@@ -161,9 +144,27 @@ export type SonareWorkletMessage =
   | SonareWorkletSetMeterIntervalMessage
   | SonareWorkletDestroyMessage;
 
+/** One external-MIDI event delivered to the main thread, lowered to MIDI 1.0
+ * bytes ready for a Web MIDI output port. */
+export interface SonareWorkletExternalMidiEvent {
+  /** Originating track lane, or 0xFFFFFFFF for transport/clock bytes. */
+  destinationId: number;
+  /** Sample position within the producing block. */
+  renderFrame: number;
+  /** MIDI 1.0 status + data bytes (1..3 entries). */
+  bytes: number[];
+}
+
+/** Batch of external-MIDI events posted from the worklet once per render block. */
+export interface SonareWorkletExternalMidiMessage {
+  type: 'externalMidi';
+  events: SonareWorkletExternalMidiEvent[];
+}
+
 export type SonareWorkletTransportMessage =
   | SonareWorkletMeterSnapshot
   | SonareWorkletSpectrumSnapshot
+  | SonareWorkletExternalMidiMessage
   | SonareEngineTelemetryRecord;
 
 export interface WorkletTransport {
@@ -310,6 +311,14 @@ export interface SonareEngineSyncMasterStripInsertParamByNameMessage {
   value: number;
 }
 
+export interface SonareEngineSyncBusStripInsertParamByNameMessage {
+  type: 'syncBusStripInsertParamByName';
+  busId: number;
+  insertIndex: number;
+  paramName: string;
+  value: number;
+}
+
 export interface SonareEngineSyncTrackStripPanMessage {
   type: 'syncTrackStripPan';
   trackId: number;
@@ -364,6 +373,13 @@ export interface SonareEngineSyncLoadSoundFontMessage {
   data: Uint8Array;
 }
 
+export interface SonareEngineSyncMidiFxMessage {
+  type: 'syncMidiFx' | 'syncClearMidiFx';
+  destinationId: number;
+  /** Engine MIDI-FX config JSON; present for 'syncMidiFx', absent for a clear. */
+  configJson?: string;
+}
+
 export interface SonareEngineSyncMidiNoteMessage {
   type: 'syncMidiNoteOn' | 'syncMidiNoteOff';
   destinationId: number;
@@ -384,16 +400,35 @@ export interface SonareEngineSyncMidiCcMessage {
   renderFrame: number;
 }
 
+export interface SonareEngineSyncMidiSysexMessage {
+  type: 'syncMidiSysex';
+  destinationId: number;
+  data: Uint8Array;
+  renderFrame: number;
+}
+
 export interface SonareEngineSyncMidiPanicMessage {
   type: 'syncMidiPanic';
   renderFrame: number;
 }
 
+export interface SonareEngineSyncMidiDestinationExternalMessage {
+  type: 'syncMidiDestinationExternal';
+  destinationId: number;
+  external: boolean;
+}
+
+export interface SonareEngineSyncExternalMidiClockMessage {
+  type: 'syncExternalMidiClock';
+  enabled: boolean;
+}
+
 export type SonareEngineInstrumentSyncMessage =
   | SonareEngineSyncBuiltinInstrumentMessage
   | SonareEngineSyncSynthInstrumentMessage
   | SonareEngineSyncSf2InstrumentMessage
-  | SonareEngineSyncLoadSoundFontMessage;
+  | SonareEngineSyncLoadSoundFontMessage
+  | SonareEngineSyncMidiFxMessage;
 
 export type SonareEngineSyncMessage =
   | SonareEngineSyncClipsMessage
@@ -411,6 +446,7 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncMasterStripInsertBypassedMessage
   | SonareEngineSyncTrackStripInsertParamByNameMessage
   | SonareEngineSyncMasterStripInsertParamByNameMessage
+  | SonareEngineSyncBusStripInsertParamByNameMessage
   | SonareEngineSyncTrackStripPanMessage
   | SonareEngineSyncTrackStripPanLawMessage
   | SonareEngineSyncTrackStripPanModeMessage
@@ -420,9 +456,13 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncSynthInstrumentMessage
   | SonareEngineSyncSf2InstrumentMessage
   | SonareEngineSyncLoadSoundFontMessage
+  | SonareEngineSyncMidiFxMessage
   | SonareEngineSyncMidiNoteMessage
   | SonareEngineSyncMidiCcMessage
-  | SonareEngineSyncMidiPanicMessage;
+  | SonareEngineSyncMidiSysexMessage
+  | SonareEngineSyncMidiPanicMessage
+  | SonareEngineSyncMidiDestinationExternalMessage
+  | SonareEngineSyncExternalMidiClockMessage;
 
 export interface WorkletPort {
   postMessage?: (message: unknown, transfer?: Transferable[]) => void;

package/src/worklet/mixer-processor.ts

@@ -0,0 +1,368 @@
+import type { MixerRealtimeBuffer } from '../index';
+import { Mixer } from '../index';
+import type { WorkletInput, WorkletOutput } from './audio_types';
+import { isWorkletMessage } from './guards';
+import type {
+  SonareWorkletMessage,
+  SonareWorkletProcessorOptions,
+  WorkletPort,
+  WorkletTransport,
+} from './messages';
+import {
+  encodeFrameHi,
+  encodeFrameLo,
+  magnitudeToDb,
+  meterRingFromSharedBuffer,
+  type SharedMeterRingWriter,
+  type SharedSpectrumRingWriter,
+  SONARE_METER_RING_RECORD_FLOATS,
+  type SonareWorkletMeterSnapshot,
+  type SonareWorkletSpectrumSnapshot,
+  spectrumRingFromSharedBuffer,
+  toDb,
+} from './protocol';
+
+/**
+ * AudioWorklet-style mixer bridge backed by the package's single `sonare.wasm`.
+ *
+ * The WASM module must already be initialized via `init()` before constructing
+ * this bridge. Each AudioWorklet input is treated as one stereo strip:
+ * `inputs[strip][0]` is left and `inputs[strip][1]` is right. Missing channels
+ * are replaced with preallocated silence.
+ */
+export class SonareWorkletProcessor {
+  readonly sampleRate: number;
+  readonly blockSize: number;
+  private mixer: Mixer;
+  private realtime: MixerRealtimeBuffer;
+  private closed = false;
+  private processedFrames = 0;
+  private lastMeterFrame = 0;
+  private meterIntervalFrames: number;
+  private spectrumIntervalFrames: number;
+  private lastSpectrumFrame = 0;
+  private transport?: WorkletTransport;
+  private meterRing?: SharedMeterRingWriter;
+  private spectrumRing?: SharedSpectrumRingWriter;
+  private spectrumBands: Float32Array;
+
+  constructor(options: SonareWorkletProcessorOptions, transport?: WorkletTransport) {
+    if (!options.sceneJson) {
+      throw new Error('sceneJson is required.');
+    }
+    this.sampleRate = options.sampleRate ?? 48000;
+    this.blockSize = options.blockSize ?? 128;
+    this.meterIntervalFrames = Math.max(0, Math.floor(options.meterIntervalFrames ?? 2048));
+    this.spectrumIntervalFrames = Math.max(0, Math.floor(options.spectrumIntervalFrames ?? 0));
+    this.transport = transport;
+    this.meterIntervalFrames = Math.max(0, Math.floor(options.meterIntervalFrames ?? 2048));
+    this.meterRing = options.meterSharedBuffer
+      ? meterRingFromSharedBuffer(options.meterSharedBuffer, options.meterRingCapacity)
+      : undefined;
+    this.spectrumRing = options.spectrumSharedBuffer
+      ? spectrumRingFromSharedBuffer(
+          options.spectrumSharedBuffer,
+          options.spectrumRingCapacity,
+          options.spectrumBands,
+        )
+      : undefined;
+    const spectrumBandCount = this.spectrumRing?.bands ?? Math.max(1, options.spectrumBands ?? 16);
+    this.spectrumBands = new Float32Array(spectrumBandCount);
+    this.mixer = Mixer.fromSceneJson(options.sceneJson, this.sampleRate, this.blockSize);
+    this.mixer.compile();
+    const sceneStripCount = this.mixer.stripCount();
+    const stripCount = options.stripCount ?? sceneStripCount;
+    if (stripCount !== sceneStripCount) {
+      throw new Error('stripCount must match the scene strip count.');
+    }
+    this.realtime = this.mixer.createRealtimeBuffer();
+  }
+
+  process(inputs: WorkletInput, outputs: WorkletOutput): boolean {
+    if (this.closed) {
+      return false;
+    }
+    const output = outputs[0];
+    const leftOut = output?.[0];
+    const rightOut = output?.[1];
+    if (!leftOut) {
+      return true;
+    }
+    const frames = leftOut.length;
+    // 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.
+    const usable = Math.min(frames, this.blockSize);
+
+    for (let strip = 0; strip < this.realtime.leftInputs.length; strip++) {
+      const input = inputs[strip];
+      const left = input?.[0];
+      const right = input?.[1];
+      const leftTarget = this.realtime.leftInputs[strip];
+      const rightTarget = this.realtime.rightInputs[strip];
+      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.subarray(0, usable));
+        }
+      } else {
+        leftTarget.fill(0);
+        rightTarget.fill(0);
+      }
+    }
+
+    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 += 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;
+  }
+
+  receiveMessage(message: SonareWorkletMessage): void {
+    if (this.closed) {
+      return;
+    }
+    if (message.type === 'destroy') {
+      this.destroy();
+      return;
+    }
+    if (message.type === 'setMeterInterval') {
+      this.meterIntervalFrames = Math.max(0, Math.floor(message.frames));
+      return;
+    }
+    if (message.type === 'scheduleInsertAutomation') {
+      this.mixer.scheduleInsertAutomation(
+        message.stripIndex,
+        message.insertIndex,
+        message.paramId,
+        message.samplePos ?? this.processedFrames,
+        message.value,
+        message.curve ?? 'linear',
+      );
+    }
+  }
+
+  destroy(): void {
+    if (!this.closed) {
+      this.mixer.delete();
+      this.closed = true;
+    }
+  }
+
+  private publishMeter(left: Float32Array, right: Float32Array): void {
+    if (!this.transport || this.meterIntervalFrames <= 0) {
+      return;
+    }
+    if (this.processedFrames - this.lastMeterFrame < this.meterIntervalFrames) {
+      return;
+    }
+    this.lastMeterFrame = this.processedFrames;
+
+    let peakL = 0;
+    let peakR = 0;
+    let sumL = 0;
+    let sumR = 0;
+    let sumLR = 0;
+    for (let i = 0; i < left.length; i++) {
+      const l = left[i] ?? 0;
+      const r = right[i] ?? 0;
+      const absL = Math.abs(l);
+      const absR = Math.abs(r);
+      if (absL > peakL) {
+        peakL = absL;
+      }
+      if (absR > peakR) {
+        peakR = absR;
+      }
+      sumL += l * l;
+      sumR += r * r;
+      sumLR += l * r;
+    }
+    const rmsL = Math.sqrt(sumL / Math.max(1, left.length));
+    const rmsR = Math.sqrt(sumR / Math.max(1, right.length));
+    const denominator = Math.sqrt(sumL * sumR);
+    const meter: SonareWorkletMeterSnapshot = {
+      type: 'meter',
+      targetId: 0,
+      frame: this.processedFrames,
+      peakDbL: toDb(peakL),
+      peakDbR: toDb(peakR),
+      rmsDbL: toDb(rmsL),
+      rmsDbR: toDb(rmsR),
+      correlation: denominator > 0 ? sumLR / denominator : 0,
+      truePeakDbL: toDb(peakL),
+      truePeakDbR: toDb(peakR),
+      momentaryLufs: Number.NaN,
+      shortTermLufs: Number.NaN,
+      integratedLufs: Number.NaN,
+      gainReductionDb: Number.NaN,
+    };
+    this.transport.onMeter?.(meter);
+    if (this.meterRing) {
+      this.writeMeterRing(meter);
+    } else {
+      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] = encodeFrameHi(meter.frame);
+    ring.records[offset + 2] = meter.targetId;
+    ring.records[offset + 3] = meter.peakDbL;
+    ring.records[offset + 4] = meter.peakDbR;
+    ring.records[offset + 5] = meter.rmsDbL;
+    ring.records[offset + 6] = meter.rmsDbR;
+    ring.records[offset + 7] = meter.correlation;
+    ring.records[offset + 8] = meter.truePeakDbL;
+    ring.records[offset + 9] = meter.truePeakDbR;
+    ring.records[offset + 10] = meter.momentaryLufs;
+    ring.records[offset + 11] = meter.shortTermLufs;
+    ring.records[offset + 12] = meter.integratedLufs;
+    ring.records[offset + 13] = meter.gainReductionDb;
+    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 publishSpectrum(left: Float32Array, right: Float32Array): void {
+    if (this.spectrumIntervalFrames <= 0) {
+      return;
+    }
+    if (this.processedFrames - this.lastSpectrumFrame < this.spectrumIntervalFrames) {
+      return;
+    }
+    this.lastSpectrumFrame = this.processedFrames;
+    this.computeSpectrum(left, right);
+    if (this.spectrumRing) {
+      this.writeSpectrumRing(this.processedFrames, this.spectrumBands);
+      return;
+    }
+    const spectrum: SonareWorkletSpectrumSnapshot = {
+      type: 'spectrum',
+      frame: this.processedFrames,
+      bands: new Float32Array(this.spectrumBands),
+    };
+    this.transport?.onSpectrum?.(spectrum);
+    this.transport?.postMessage?.(spectrum);
+  }
+
+  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;
+      for (let i = 0; i < n; i++) {
+        const sample = 0.5 * ((left[i] ?? 0) + (right[i] ?? 0));
+        const phase = (-2 * Math.PI * bin * i) / n;
+        real += sample * Math.cos(phase);
+        imag += sample * Math.sin(phase);
+      }
+      this.spectrumBands[band] = magnitudeToDb((2 * Math.hypot(real, imag)) / n);
+    }
+  }
+
+  private writeSpectrumRing(frame: number, bands: Float32Array): void {
+    const ring = this.spectrumRing;
+    if (!ring) {
+      return;
+    }
+    const writeIndex = Atomics.load(ring.header, 0);
+    const offset = (writeIndex % ring.capacity) * ring.recordFloats;
+    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);
+    // 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.)
+  }
+}
+
+export function registerSonareWorkletProcessor(name = 'sonare-worklet-processor'): void {
+  const scope = globalThis as unknown as {
+    AudioWorkletProcessor?: new () => object;
+    registerProcessor?: (processorName: string, processorCtor: unknown) => void;
+  };
+  if (!scope.AudioWorkletProcessor || !scope.registerProcessor) {
+    throw new Error('AudioWorkletProcessor is not available in this context.');
+  }
+  const Base = scope.AudioWorkletProcessor;
+  class RegisteredSonareWorkletProcessor extends Base {
+    private bridge: SonareWorkletProcessor;
+    readonly port?: WorkletPort;
+
+    constructor(options?: { processorOptions?: SonareWorkletProcessorOptions }) {
+      super();
+      const port = this.port;
+      this.bridge = new SonareWorkletProcessor(options?.processorOptions ?? { sceneJson: '' }, {
+        postMessage: (message) => port?.postMessage?.(message),
+      });
+      const onMessage = (event: { data: unknown }) => {
+        if (isWorkletMessage(event.data)) {
+          this.bridge.receiveMessage(event.data);
+        }
+      };
+      if (port?.addEventListener) {
+        port.addEventListener('message', onMessage);
+        port.start?.();
+      } else if (port) {
+        port.onmessage = onMessage;
+      }
+    }
+
+    process(inputs: WorkletInput, outputs: WorkletOutput): boolean {
+      return this.bridge.process(inputs, outputs);
+    }
+  }
+  scope.registerProcessor(name, RegisteredSonareWorkletProcessor);
+}

package/src/worklet/protocol.ts

@@ -119,6 +119,9 @@ export enum SonareEngineTelemetryError {
   AutomationBindTargetOverflow = 11,
   StaleAutomationLanes = 12,
   SmoothedParameterCapacity = 13,
+  CommandBacklogDeferred = 14,
+  ClipPageUnderrun = 15,
+  InsertAutomationOverflow = 16,
 }
 
 export interface SonareMeterRingBuffer {