@libraz/libsonare 1.5.5 → 1.7.0

package/src/worklet/guards.ts

@@ -1,6 +1,8 @@
+import type { EngineCaptureStatus } from '../index';
 import type {
   SonareEngineCaptureRequestMessage,
-  SonareEngineCaptureResponseMessage,
+  SonareEngineCaptureResponseMessageInternal,
+  SonareEngineClipPageRequestMessage,
   SonareEngineSyncMessage,
   SonareEngineTransportRequestMessage,
   SonareEngineTransportResponseMessage,
@@ -39,7 +41,9 @@ export function isEngineSyncMessage(value: unknown): value is SonareEngineSyncMe
     value.type === 'syncClipsDelta' ||
     value.type === 'syncClipPageProvider' ||
     value.type === 'syncClipPage' ||
+    value.type === 'syncClipPageClear' ||
     value.type === 'syncClipPageCommit' ||
+    value.type === 'syncClipPageDestroy' ||
     value.type === 'syncMidiClips' ||
     value.type === 'syncMarkers' ||
     value.type === 'syncMetronome' ||
@@ -68,10 +72,12 @@ export function isEngineSyncMessage(value: unknown): value is SonareEngineSyncMe
     value.type === 'syncMidiNoteOn' ||
     value.type === 'syncMidiNoteOff' ||
     value.type === 'syncMidiCc' ||
+    value.type === 'syncMidiUmp' ||
     value.type === 'syncMidiSysex' ||
     value.type === 'syncMidiPanic' ||
     value.type === 'syncMidiDestinationExternal' ||
-    value.type === 'syncExternalMidiClock'
+    value.type === 'syncExternalMidiClock' ||
+    value.type === 'destroy'
   );
 }
 
@@ -86,17 +92,108 @@ export function isEngineCaptureRequestMessage(
   );
 }
 
-export function isEngineCaptureResponseMessage(
-  value: unknown,
-): value is SonareEngineCaptureResponseMessage {
+function isCaptureStatus(value: unknown): value is EngineCaptureStatus {
   return (
     isRecord(value) &&
-    value.type === 'captureResponse' &&
-    typeof value.requestId === 'number' &&
-    typeof value.ok === 'boolean'
+    typeof value.capturedFrames === 'number' &&
+    Number.isSafeInteger(value.capturedFrames) &&
+    value.capturedFrames >= 0 &&
+    typeof value.overflowCount === 'number' &&
+    Number.isSafeInteger(value.overflowCount) &&
+    value.overflowCount >= 0 &&
+    typeof value.armed === 'boolean' &&
+    typeof value.punchEnabled === 'boolean' &&
+    (value.source === 'input' || value.source === 'output') &&
+    typeof value.recordOffsetSamples === 'number' &&
+    Number.isSafeInteger(value.recordOffsetSamples)
   );
 }
 
+function isCaptureChannel(value: unknown): value is Float32Array {
+  // Capture responses are transferred out of the worklet. A typed view onto
+  // the WASM heap or a SharedArrayBuffer must not cross that boundary: the
+  // former can be detached by memory growth and the latter cannot be listed
+  // in a transfer list. `instanceof` also rejects boxed number arrays.
+  return (
+    value instanceof Float32Array &&
+    typeof ArrayBuffer !== 'undefined' &&
+    value.buffer instanceof ArrayBuffer
+  );
+}
+
+function isCaptureChannels(value: unknown): value is Float32Array[] {
+  return Array.isArray(value) && value.every((channel) => isCaptureChannel(channel));
+}
+
+function hasOwn(value: Record<string, unknown>, key: string): boolean {
+  // biome-ignore lint/suspicious/noPrototypeBuiltins: Object.hasOwn is newer than the ES2020 target.
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+/** Return a request ID even when the response payload itself is malformed. */
+export function engineCaptureResponseRequestId(value: unknown): number | undefined {
+  if (
+    !isRecord(value) ||
+    value.type !== 'captureResponse' ||
+    typeof value.requestId !== 'number' ||
+    !Number.isSafeInteger(value.requestId)
+  ) {
+    return undefined;
+  }
+  return value.requestId;
+}
+
+export function isEngineCaptureResponseMessage(
+  value: unknown,
+): value is SonareEngineCaptureResponseMessageInternal {
+  const requestId = engineCaptureResponseRequestId(value);
+  if (requestId === undefined || !isRecord(value)) {
+    return false;
+  }
+  if (value.ok === false) {
+    return (
+      typeof value.error === 'string' && !hasOwn(value, 'status') && !hasOwn(value, 'channels')
+    );
+  }
+  if (value.ok !== true || hasOwn(value, 'error')) {
+    return false;
+  }
+  const hasStatus = hasOwn(value, 'status');
+  const hasChannels = hasOwn(value, 'channels');
+  if (hasStatus && hasChannels) {
+    return false;
+  }
+  if (hasStatus) {
+    return isCaptureStatus(value.status);
+  }
+  if (hasChannels) {
+    return isCaptureChannels(value.channels);
+  }
+  return true;
+}
+
+/**
+ * Check that a strict success response belongs to the requested operation.
+ * Failure responses are operation-independent and are therefore valid for
+ * every pending request (the node rejects them after this check).
+ */
+export function isEngineCaptureResponseForOperation(
+  response: SonareEngineCaptureResponseMessageInternal,
+  op: SonareEngineCaptureRequestMessage['op'],
+): boolean {
+  if (!response.ok) {
+    return true;
+  }
+  switch (op) {
+    case 'status':
+      return 'status' in response;
+    case 'read':
+      return 'channels' in response;
+    case 'reset':
+      return !('status' in response) && !('channels' in response);
+  }
+}
+
 export function isEngineTransportRequestMessage(
   value: unknown,
 ): value is SonareEngineTransportRequestMessage {
@@ -147,6 +244,22 @@ export function isExternalMidiBatchMessage(
   return isRecord(value) && value.type === 'externalMidi' && Array.isArray(value.events);
 }
 
+export function isClipPageRequestMessage(
+  value: unknown,
+): value is SonareEngineClipPageRequestMessage {
+  return (
+    isRecord(value) &&
+    value.type === 'clipPageRequest' &&
+    Array.isArray(value.requests) &&
+    value.requests.every(
+      (request) =>
+        isRecord(request) &&
+        typeof request.clipId === 'number' &&
+        typeof request.pageIndex === 'number',
+    )
+  );
+}
+
 export function isMeterSnapshot(value: unknown): value is SonareWorkletMeterSnapshot {
   return (
     isRecord(value) &&

package/src/worklet/messages.ts

@@ -6,11 +6,13 @@ import type {
   EngineMarker,
   EngineMetronomeConfig,
   EngineMidiClipSchedule,
+  EngineParameterInfo,
   EngineTempoSegment,
   EngineTimeSignatureSegment,
   EngineTrackLane,
   EngineTransportState,
   RealtimeVoiceChangerConfigInput,
+  RealtimeVoiceChangerPodConfig,
 } from '../index';
 import type { AutomationCurve } from '../public_types';
 import type {
@@ -55,6 +57,16 @@ export interface SonareRealtimeEngineWorkletProcessorOptions {
   scopeBands?: number;
   scopeSharedBuffer?: SharedArrayBuffer;
   scopeRingCapacity?: number;
+  /**
+   * Lock-free SPSC queue for clip-page cache misses. Supplying this is required
+   * for realtime-safe OPFS streaming: it avoids both embind object creation and
+   * postMessage structured cloning from AudioWorklet process().
+   */
+  clipPageRequestSharedBuffer?: SharedArrayBuffer;
+  clipPageRequestRingCapacity?: number;
+  /** Lock-free worklet-to-main-thread MIDI-1 output ring. */
+  externalMidiSharedBuffer?: SharedArrayBuffer;
+  externalMidiRingCapacity?: number;
 }
 
 export interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
@@ -66,7 +78,8 @@ export interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
 
 export interface SonareRealtimeVoiceChangerSetConfigMessage {
   type: 'setConfig';
-  preset: RealtimeVoiceChangerConfigInput;
+  /** Pre-normalized by the main thread; never JSON parsed in the worklet. */
+  config: RealtimeVoiceChangerPodConfig;
 }
 
 export interface SonareRealtimeVoiceChangerResetMessage {
@@ -88,6 +101,10 @@ export interface SonareRealtimeEngineNodeCapabilities {
   sharedArrayBuffer: boolean;
   atomics: boolean;
   audioWorklet: boolean;
+  /** True only when clip-page misses use the bounded SAB ring. */
+  clipPageRequestsRealtimeSafe: boolean;
+  /** True when external MIDI uses the SAB output ring rather than postMessage. */
+  externalMidiRealtimeSafe: boolean;
   engineAbiVersion?: number;
   expectedEngineAbiVersion?: number;
   abiCompatible?: boolean;
@@ -161,18 +178,27 @@ export interface SonareWorkletExternalMidiMessage {
   events: SonareWorkletExternalMidiEvent[];
 }
 
+/** A control-plane sync message that the worklet rejected without crashing. */
+export interface SonareEngineSyncErrorMessage {
+  type: 'syncError';
+  syncType: SonareEngineSyncMessage['type'];
+  message: string;
+}
+
 export type SonareWorkletTransportMessage =
   | SonareWorkletMeterSnapshot
   | SonareWorkletSpectrumSnapshot
   | SonareWorkletExternalMidiMessage
+  | SonareEngineClipPageRequestMessage
   | SonareEngineTelemetryRecord;
 
 export interface WorkletTransport {
   postMessage?: (
     message:
       | SonareWorkletTransportMessage
-      | SonareEngineCaptureResponseMessage
-      | SonareEngineTransportResponseMessage,
+      | SonareEngineCaptureResponseMessageInternal
+      | SonareEngineTransportResponseMessage
+      | SonareEngineSyncErrorMessage,
     transfer?: Transferable[],
   ) => void;
   onMeter?: (meter: SonareWorkletMeterSnapshot) => void;
@@ -183,6 +209,7 @@ export interface ResolvedMetronomeConfig {
   beatGain: number;
   accentGain: number;
   clickSamples: number;
+  clickSeconds: number;
 }
 
 // Fallback metronome gains/click length used by the worklet consumer until the
@@ -192,6 +219,7 @@ export const DEFAULT_METRONOME_CONFIG: ResolvedMetronomeConfig = {
   beatGain: 0.35,
   accentGain: 0.7,
   clickSamples: 0,
+  clickSeconds: 0,
 };
 
 export function resolveMetronomeConfig(config: EngineMetronomeConfig): ResolvedMetronomeConfig {
@@ -199,6 +227,7 @@ export function resolveMetronomeConfig(config: EngineMetronomeConfig): ResolvedM
     beatGain: config.beatGain ?? DEFAULT_METRONOME_CONFIG.beatGain,
     accentGain: config.accentGain ?? DEFAULT_METRONOME_CONFIG.accentGain,
     clickSamples: config.clickSamples ?? DEFAULT_METRONOME_CONFIG.clickSamples,
+    clickSeconds: config.clickSeconds ?? DEFAULT_METRONOME_CONFIG.clickSeconds,
   };
   if (
     !Number.isFinite(resolved.beatGain) ||
@@ -207,6 +236,8 @@ export function resolveMetronomeConfig(config: EngineMetronomeConfig): ResolvedM
     resolved.accentGain < 0 ||
     !Number.isInteger(resolved.clickSamples) ||
     resolved.clickSamples < 0 ||
+    !Number.isFinite(resolved.clickSeconds) ||
+    resolved.clickSeconds < 0 ||
     resolved.clickSamples > 384000 ||
     (config.clickSeconds !== undefined &&
       (!Number.isFinite(config.clickSeconds) || config.clickSeconds < 0 || config.clickSeconds > 1))
@@ -220,8 +251,9 @@ export function resolveMetronomeConfig(config: EngineMetronomeConfig): ResolvedM
 // 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.
+// fixed-size SAB command record. Their port handlers still execute on the
+// AudioWorklet rendering thread, so consumers must validate them without
+// allocation and publish bounded snapshots for process() to consume.
 export interface SonareEngineSyncClipsMessage {
   type: 'syncClips';
   clips: EngineClip[];
@@ -237,7 +269,8 @@ export interface SonareEngineSyncClipsDeltaMessage {
 export interface SonareEngineSyncClipPageProviderMessage {
   type: 'syncClipPageProvider';
   clipId: number;
-  clip: EngineClip;
+  /** Omitted when an OPFS stream is primed before its clip is scheduled. */
+  clip?: EngineClip;
   numChannels: number;
   numSamples: number;
   pageFrames: number;
@@ -251,10 +284,41 @@ export interface SonareEngineSyncClipPageMessage {
   channels: Float32Array[];
 }
 
+/** Evicts one page after the main-thread sliding window advances. */
+export interface SonareEngineSyncClipPageClearMessage {
+  type: 'syncClipPageClear';
+  clipId: number;
+  pageIndex: number;
+}
+
+/** Releases a provider whose clip was removed or whose stream was closed. */
+export interface SonareEngineSyncClipPageDestroyMessage {
+  type: 'syncClipPageDestroy';
+  clipId: number;
+}
+
 /** Makes a fully supplied paged clip visible to the audio engine. */
 export interface SonareEngineSyncClipPageCommitMessage {
   type: 'syncClipPageCommit';
   clipId: number;
+  /**
+   * Clip schedule to publish with a provider that was primed before its
+   * schedule was known. The original pre-baked push path supplies it on the
+   * provider message instead.
+   */
+  clip?: EngineClip;
+}
+
+/**
+ * A bounded batch of page misses emitted by the AudioWorklet. The main thread
+ * resolves these from OPFS and responds with `syncClipPage`; a missing page is
+ * silent until that response arrives.
+ */
+export interface SonareEngineClipPageRequestMessage {
+  type: 'clipPageRequest';
+  requests: Array<{ clipId: number; pageIndex: number }>;
+  /** Number of misses dropped because a bounded native or SAB request queue was full. */
+  dropped?: number;
 }
 
 export interface SonareEngineSyncMidiClipsMessage {
@@ -278,6 +342,12 @@ export interface SonareEngineSyncAutomationMessage {
   points: EngineAutomationPoint[];
 }
 
+/** Replaces the live engine's registered custom-parameter set. */
+export interface SonareEngineSyncParametersMessage {
+  type: 'syncParameters';
+  parameters: EngineParameterInfo[];
+}
+
 export interface SonareEngineSyncTempoMessage {
   type: 'syncTempo';
   bpm: number;
@@ -403,7 +473,12 @@ export interface SonareEngineSyncSynthInstrumentMessage {
 export interface SonareEngineSyncSf2InstrumentMessage {
   type: 'syncSf2Instrument';
   destinationId: number;
-  config: { destinationId?: number; gain?: number; polyphony?: number };
+  config: {
+    destinationId?: number;
+    gain?: number;
+    polyphony?: number;
+    preferModelForModeledFamilies?: boolean;
+  };
 }
 
 export interface SonareEngineSyncLoadSoundFontMessage {
@@ -438,6 +513,13 @@ export interface SonareEngineSyncMidiCcMessage {
   renderFrame: number;
 }
 
+export interface SonareEngineSyncMidiUmpMessage {
+  type: 'syncMidiUmp';
+  destinationId: number;
+  word0: number;
+  renderFrame: number;
+}
+
 export interface SonareEngineSyncMidiSysexMessage {
   type: 'syncMidiSysex';
   destinationId: number;
@@ -461,6 +543,34 @@ export interface SonareEngineSyncExternalMidiClockMessage {
   enabled: boolean;
 }
 
+export interface SonareEngineSyncMidiInputSourceMessage {
+  type: 'syncMidiInputSource' | 'syncClearMidiInputSource';
+  destinationId?: number;
+}
+
+export interface SonareEngineSyncMidiCcBindingMessage {
+  type: 'syncMidiCcBinding';
+  channel: number;
+  controller: number;
+  paramId: number;
+  minValue: number;
+  maxValue: number;
+}
+
+export interface SonareEngineSyncMidiInputEventMessage {
+  type: 'syncMidiInputNoteOn' | 'syncMidiInputNoteOff' | 'syncMidiInputCc';
+  group: number;
+  channel: number;
+  data0: number;
+  data1: number;
+  portTimeSamples: number;
+}
+
+/** Releases the realtime engine and all worklet-owned clip buffers. */
+export interface SonareEngineDestroyMessage {
+  type: 'destroy';
+}
+
 export type SonareEngineInstrumentSyncMessage =
   | SonareEngineSyncBuiltinInstrumentMessage
   | SonareEngineSyncSynthInstrumentMessage
@@ -473,11 +583,14 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncClipsDeltaMessage
   | SonareEngineSyncClipPageProviderMessage
   | SonareEngineSyncClipPageMessage
+  | SonareEngineSyncClipPageClearMessage
   | SonareEngineSyncClipPageCommitMessage
+  | SonareEngineSyncClipPageDestroyMessage
   | SonareEngineSyncMidiClipsMessage
   | SonareEngineSyncMarkersMessage
   | SonareEngineSyncMetronomeMessage
   | SonareEngineSyncAutomationMessage
+  | SonareEngineSyncParametersMessage
   | SonareEngineSyncTempoMessage
   | SonareEngineSyncMixerMessage
   | SonareEngineSyncCaptureMessage
@@ -500,10 +613,15 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncMidiFxMessage
   | SonareEngineSyncMidiNoteMessage
   | SonareEngineSyncMidiCcMessage
+  | SonareEngineSyncMidiUmpMessage
   | SonareEngineSyncMidiSysexMessage
   | SonareEngineSyncMidiPanicMessage
   | SonareEngineSyncMidiDestinationExternalMessage
-  | SonareEngineSyncExternalMidiClockMessage;
+  | SonareEngineSyncExternalMidiClockMessage
+  | SonareEngineSyncMidiInputSourceMessage
+  | SonareEngineSyncMidiCcBindingMessage
+  | SonareEngineSyncMidiInputEventMessage
+  | SonareEngineDestroyMessage;
 
 export interface WorkletPort {
   postMessage?: (message: unknown, transfer?: Transferable[]) => void;
@@ -518,6 +636,12 @@ export interface SonareEngineCaptureRequestMessage {
   op: 'status' | 'read' | 'reset';
 }
 
+/**
+ * Public capture response shape retained for source compatibility.
+ *
+ * The worklet wire protocol is stricter than this legacy structural type; use
+ * `SonareEngineCaptureResponseMessageInternal` inside the implementation.
+ */
 export interface SonareEngineCaptureResponseMessage {
   type: 'captureResponse';
   requestId: number;
@@ -527,6 +651,40 @@ export interface SonareEngineCaptureResponseMessage {
   error?: string;
 }
 
+interface SonareEngineCaptureStatusResponseMessageInternal {
+  type: 'captureResponse';
+  requestId: number;
+  ok: true;
+  status: EngineCaptureStatus;
+}
+
+interface SonareEngineCaptureReadResponseMessageInternal {
+  type: 'captureResponse';
+  requestId: number;
+  ok: true;
+  channels: Float32Array[];
+}
+
+interface SonareEngineCaptureResetResponseMessageInternal {
+  type: 'captureResponse';
+  requestId: number;
+  ok: true;
+}
+
+interface SonareEngineCaptureErrorResponseMessageInternal {
+  type: 'captureResponse';
+  requestId: number;
+  ok: false;
+  error: string;
+}
+
+/** Strict wire response type used only by the worklet implementation. */
+export type SonareEngineCaptureResponseMessageInternal =
+  | SonareEngineCaptureStatusResponseMessageInternal
+  | SonareEngineCaptureReadResponseMessageInternal
+  | SonareEngineCaptureResetResponseMessageInternal
+  | SonareEngineCaptureErrorResponseMessageInternal;
+
 export interface SonareEngineTransportRequestMessage {
   type: 'transportRequest';
   requestId: number;