@libraz/libsonare 1.7.1 → 1.8.0

package/src/worklet/guards.ts

@@ -6,6 +6,7 @@ import type {
   SonareEngineSyncMessage,
   SonareEngineTransportRequestMessage,
   SonareEngineTransportResponseMessage,
+  SonarePlaybackMessage,
   SonareRealtimeVoiceChangerMessage,
   SonareWorkletExternalMidiMessage,
   SonareWorkletMessage,
@@ -32,52 +33,87 @@ export function isEngineCommandRecord(value: unknown): value is SonareEngineComm
   return isRecord(value) && typeof value.type === 'number';
 }
 
+/**
+ * Every discriminant the worklet accepts on the control plane, derived from the
+ * `SonareEngineSyncMessage` union rather than restated as literals.
+ *
+ * The `Record<SonareEngineSyncMessage['type'], true>` annotation rejects a
+ * missing key and the object literal's excess-property check rejects a stale
+ * one, so a union member that never reaches this table is a compile error
+ * instead of a message the port drops in silence.
+ */
+export const ENGINE_SYNC_MESSAGE_TYPES: Record<SonareEngineSyncMessage['type'], true> = {
+  destroy: true,
+  syncAutomation: true,
+  syncBuiltinInstrument: true,
+  syncBusStripDualPan: true,
+  syncBusStripEqBand: true,
+  syncBusStripInsertBypassed: true,
+  syncBusStripInsertParamByName: true,
+  syncBusStripPan: true,
+  syncBusStripPanLaw: true,
+  syncBusStripPanMode: true,
+  syncCapture: true,
+  syncClearMidiFx: true,
+  syncClearMidiInputSource: true,
+  syncClipPage: true,
+  syncClipPageClear: true,
+  syncClipPageCommit: true,
+  syncClipPageDestroy: true,
+  syncClipPagePrefetchFrames: true,
+  syncClipPageProvider: true,
+  syncClips: true,
+  syncClipsDelta: true,
+  syncExternalMidiClock: true,
+  syncLoadSoundFont: true,
+  syncMarkers: true,
+  syncMasterStripEqBand: true,
+  syncMasterStripInsertBypassed: true,
+  syncMasterStripInsertParamByName: true,
+  syncMetronome: true,
+  syncMidiCc: true,
+  syncMidiCcBinding: true,
+  syncMidiChannelPressure: true,
+  syncMidiClips: true,
+  syncMidiDestinationExternal: true,
+  syncMidiFx: true,
+  syncMidiInputChannelPressure: true,
+  syncMidiInputCc: true,
+  syncMidiInputNoteOff: true,
+  syncMidiInputNoteOn: true,
+  syncMidiInputPitchBend: true,
+  syncMidiInputPolyPressure: true,
+  syncMidiInputSource: true,
+  syncMidiNoteOff: true,
+  syncMidiNoteOn: true,
+  syncMidiPanic: true,
+  syncMidiPitchBend: true,
+  syncMidiPolyPressure: true,
+  syncMidiSysex: true,
+  syncMidiUmp: true,
+  syncMixer: true,
+  syncParameters: true,
+  syncSf2Instrument: true,
+  syncSynthInstrument: true,
+  syncTempo: true,
+  syncTrackStripChannelDelaySamples: true,
+  syncTrackStripDualPan: true,
+  syncTrackStripEqBand: true,
+  syncTrackStripInsertBypassed: true,
+  syncTrackStripInsertParamByName: true,
+  syncTrackStripPan: true,
+  syncTrackStripPanLaw: true,
+  syncTrackStripPanMode: true,
+  syncWarpVoiceCapacity: true,
+};
+
+// A Set rather than a property lookup on the table: an inherited member name
+// ('constructor', 'toString') must not read as an accepted discriminant.
+const engineSyncMessageTypes: ReadonlySet<string> = new Set(Object.keys(ENGINE_SYNC_MESSAGE_TYPES));
+
 export function isEngineSyncMessage(value: unknown): value is SonareEngineSyncMessage {
-  if (!isRecord(value) || typeof value.type !== 'string') {
-    return false;
-  }
   return (
-    value.type === 'syncClips' ||
-    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' ||
-    value.type === 'syncAutomation' ||
-    value.type === 'syncTempo' ||
-    value.type === 'syncMixer' ||
-    value.type === 'syncCapture' ||
-    value.type === 'syncTrackStripEqBand' ||
-    value.type === 'syncMasterStripEqBand' ||
-    value.type === 'syncTrackStripInsertBypassed' ||
-    value.type === 'syncMasterStripInsertBypassed' ||
-    value.type === 'syncTrackStripInsertParamByName' ||
-    value.type === 'syncMasterStripInsertParamByName' ||
-    value.type === 'syncBusStripInsertParamByName' ||
-    value.type === 'syncTrackStripPan' ||
-    value.type === 'syncTrackStripPanLaw' ||
-    value.type === 'syncTrackStripPanMode' ||
-    value.type === 'syncTrackStripDualPan' ||
-    value.type === 'syncTrackStripChannelDelaySamples' ||
-    value.type === 'syncBuiltinInstrument' ||
-    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 === 'syncMidiUmp' ||
-    value.type === 'syncMidiSysex' ||
-    value.type === 'syncMidiPanic' ||
-    value.type === 'syncMidiDestinationExternal' ||
-    value.type === 'syncExternalMidiClock' ||
-    value.type === 'destroy'
+    isRecord(value) && typeof value.type === 'string' && engineSyncMessageTypes.has(value.type)
   );
 }
 
@@ -225,6 +261,31 @@ export function isRealtimeVoiceChangerMessage(
   return value.type === 'setConfig' || value.type === 'reset' || value.type === 'destroy';
 }
 
+const isOptionalNumber = (value: unknown): boolean =>
+  value === undefined || typeof value === 'number';
+
+export function isPlaybackMessage(value: unknown): value is SonarePlaybackMessage {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return false;
+  }
+  switch (value.type) {
+    case 'config':
+      return typeof value.config === 'string';
+    case 'orientation':
+      return (
+        typeof value.yaw === 'number' &&
+        isOptionalNumber(value.pitch) &&
+        isOptionalNumber(value.roll)
+      );
+    case 'reset':
+    case 'diagnostics':
+    case 'destroy':
+      return true;
+    default:
+      return false;
+  }
+}
+
 export function isEngineTelemetryRecord(value: unknown): value is SonareEngineTelemetryRecord {
   return (
     isRecord(value) &&
@@ -273,3 +334,38 @@ export function isMeterSnapshot(value: unknown): value is SonareWorkletMeterSnap
     (typeof value.targetId === 'number' || value.targetId === undefined)
   );
 }
+
+/**
+ * Resolves an integer option, refusing anything the field's own domain cannot
+ * hold instead of rounding it into range.
+ *
+ * Rounding hands the caller a working object configured with a value they never
+ * asked for, and nothing downstream can tell that apart from the value they
+ * meant. A ceiling, where one exists, stays with the layer that owns it.
+ */
+export function requireIntegerOption(
+  value: number | undefined,
+  fallback: number,
+  name: string,
+  minimum: number,
+): number {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < minimum) {
+    throw new RangeError(`${name} must be an integer of at least ${minimum}`);
+  }
+  return resolved;
+}
+
+/** As {@link requireIntegerOption}, for a field whose domain admits either sign. */
+export function requireInteger(value: number | undefined, fallback: number, name: string): number {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved)) {
+    throw new RangeError(`${name} must be an integer`);
+  }
+  return resolved;
+}
+
+/** Resolves the channel count every worklet entry point accepts on its options. */
+export function requireChannelCount(channelCount: number | undefined, fallback: number): number {
+  return requireIntegerOption(channelCount, fallback, 'channelCount', 1);
+}

package/src/worklet/messages.ts

@@ -11,6 +11,8 @@ import type {
   EngineTimeSignatureSegment,
   EngineTrackLane,
   EngineTransportState,
+  PlaybackDiagnostics,
+  PlaybackRendererConfig,
   RealtimeVoiceChangerConfigInput,
   RealtimeVoiceChangerPodConfig,
 } from '../index';
@@ -67,6 +69,13 @@ export interface SonareRealtimeEngineWorkletProcessorOptions {
   /** Lock-free worklet-to-main-thread MIDI-1 output ring. */
   externalMidiSharedBuffer?: SharedArrayBuffer;
   externalMidiRingCapacity?: number;
+  /**
+   * Route the PFL/AFL cue bus to the processor's SECOND output instead of
+   * folding it into the program output. Off by default, so an existing
+   * single-output host keeps its current mix sample for sample. The node must
+   * be constructed with two outputs for the cue to be audible.
+   */
+  cueOutput?: boolean;
 }
 
 export interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
@@ -95,6 +104,87 @@ export type SonareRealtimeVoiceChangerMessage =
   | SonareRealtimeVoiceChangerResetMessage
   | SonareRealtimeVoiceChangerDestroyMessage;
 
+export interface SonarePlaybackWorkletProcessorOptions {
+  /** Renderer configuration; parsed once, in the processor constructor. Default `{}`. */
+  config?: PlaybackRendererConfig | string;
+  /**
+   * SHRF v1 bytes, required for a headphones target (e.g. the package asset
+   * `./hrtf/default.shrf`). Copied into the renderer at construction.
+   */
+  hrtf?: ArrayBuffer | Uint8Array;
+  /** Largest render quantum the processor accepts. Default 128. */
+  maxBlockSize?: number;
+  /** Defaults to the AudioWorkletGlobalScope `sampleRate`, then 48000. */
+  sampleRate?: number;
+}
+
+export interface SonarePlaybackNodeOptions extends SonarePlaybackWorkletProcessorOptions {
+  processorName?: string;
+  nodeFactory?: (
+    context: BaseAudioContext,
+    processorName: string,
+    options: AudioWorkletNodeOptions,
+  ) => AudioWorkletNode;
+}
+
+export interface SonarePlaybackConfigMessage {
+  type: 'config';
+  /** A complete configuration document, serialized on the main thread. */
+  config: string;
+}
+
+export interface SonarePlaybackOrientationMessage {
+  type: 'orientation';
+  /** Degrees; see `PlaybackRenderer.setHeadOrientation`. */
+  yaw: number;
+  pitch?: number;
+  roll?: number;
+}
+
+/** Clears the pipeline after a seek; the handler runs between render quanta. */
+export interface SonarePlaybackResetMessage {
+  type: 'reset';
+}
+
+/** Requests a {@link SonarePlaybackDiagnosticsReplyMessage}. */
+export interface SonarePlaybackDiagnosticsRequestMessage {
+  type: 'diagnostics';
+}
+
+export interface SonarePlaybackDestroyMessage {
+  type: 'destroy';
+}
+
+export type SonarePlaybackMessage =
+  | SonarePlaybackConfigMessage
+  | SonarePlaybackOrientationMessage
+  | SonarePlaybackResetMessage
+  | SonarePlaybackDiagnosticsRequestMessage
+  | SonarePlaybackDestroyMessage;
+
+/** The renderer's diagnostics plus the worklet's own block counter. */
+export interface SonarePlaybackWorkletDiagnostics extends PlaybackDiagnostics {
+  /**
+   * Render quanta whose input channel count the renderer does not accept
+   * (not 1, 2, 6 or 8 under `"auto"`; not the fixed layout's count otherwise).
+   * Each was rendered as silence on the active input layout, so the timeline
+   * still advanced.
+   */
+  unsupported_input_blocks: number;
+}
+
+export interface SonarePlaybackDiagnosticsReplyMessage {
+  type: 'diagnostics';
+  diagnostics: SonarePlaybackWorkletDiagnostics;
+}
+
+/** Posted when a control message is refused (e.g. a changed prepare key). */
+export interface SonarePlaybackErrorMessage {
+  type: 'error';
+  request: SonarePlaybackMessage['type'];
+  message: string;
+}
+
 export interface SonareRealtimeEngineNodeCapabilities {
   mode: 'sab' | 'postMessage';
   runtimeTarget: 'embind';
@@ -105,6 +195,11 @@ export interface SonareRealtimeEngineNodeCapabilities {
   clipPageRequestsRealtimeSafe: boolean;
   /** True when external MIDI uses the SAB output ring rather than postMessage. */
   externalMidiRealtimeSafe: boolean;
+  /**
+   * True when the node carries a second output fed by the PFL/AFL cue bus. When
+   * false the cue is folded into the program output, as it always was.
+   */
+  cueOutput: boolean;
   engineAbiVersion?: number;
   expectedEngineAbiVersion?: number;
   abiCompatible?: boolean;
@@ -181,7 +276,13 @@ export interface SonareWorkletExternalMidiMessage {
 /** A control-plane sync message that the worklet rejected without crashing. */
 export interface SonareEngineSyncErrorMessage {
   type: 'syncError';
-  syncType: SonareEngineSyncMessage['type'];
+  /**
+   * Discriminant of the rejected sync. Usually a known member, but a
+   * `sync`-prefixed type this build does not recognize is reported here too
+   * rather than dropped, so the set is open. `Record<never, never>` keeps the
+   * known members as editor completions instead of collapsing to `string`.
+   */
+  syncType: SonareEngineSyncMessage['type'] | (string & Record<never, never>);
   message: string;
 }
 
@@ -284,6 +385,27 @@ export interface SonareEngineSyncClipPageMessage {
   channels: Float32Array[];
 }
 
+/**
+ * Sets the worklet engine's clip-page look-ahead window in timeline frames, so
+ * the audio thread reports the pages it is about to read before it reads them.
+ * 0 disables the look-ahead.
+ */
+export interface SonareEngineSyncClipPagePrefetchFramesMessage {
+  type: 'syncClipPagePrefetchFrames';
+  frames: number;
+}
+
+/**
+ * Sets the worklet engine's concurrent time-stretch voice capacity. The
+ * capacity was already validated (and applied to the offline engine) by the
+ * caller, so the worklet side just mirrors the accepted value; the pool
+ * rebuild itself happens on the audio thread, at the next block boundary.
+ */
+export interface SonareEngineSyncWarpVoiceCapacityMessage {
+  type: 'syncWarpVoiceCapacity';
+  voices: number;
+}
+
 /** Evicts one page after the main-thread sliding window advances. */
 export interface SonareEngineSyncClipPageClearMessage {
   type: 'syncClipPageClear';
@@ -356,15 +478,57 @@ export interface SonareEngineSyncTempoMessage {
   timeSignatureSegments?: EngineTimeSignatureSegment[];
 }
 
+export type SonareEngineSyncMixerInsertParamOverride =
+  | {
+      kind: 'track';
+      trackId: number;
+      insertIndex: number;
+      paramName: string;
+      value: number;
+    }
+  | {
+      kind: 'bus';
+      busId: number;
+      insertIndex: number;
+      paramName: string;
+      value: number;
+    }
+  | {
+      kind: 'master';
+      insertIndex: number;
+      paramName: string;
+      value: number;
+    };
+
 export interface SonareEngineSyncMixerMessage {
   type: 'syncMixer';
+  /** Apply only supplied sidechain bindings; preserve current mixer topology. */
+  sidechainDelta?: boolean;
   lanes: EngineTrackLane[];
   buses?: EngineBus[];
   trackStrips?: Array<{ trackId: number; sceneJson: string }>;
   busStrips?: Array<{ busId: number; sceneJson: string }>;
   masterStripJson?: string;
+  /** Retained by-name insert values, applied after strip and sidechain replay. */
+  insertParamOverrides?: SonareEngineSyncMixerInsertParamOverride[];
+  /** Explicit full strip replacements that must reset retained insert state. */
+  forceInsertResets?: Array<
+    { kind: 'track'; trackId: number } | { kind: 'bus'; busId: number } | { kind: 'master' }
+  >;
   /** Lane insert sidechain bindings (replayed after lanes/strips). */
   laneSidechains?: Array<{ trackId: number; insertIndex: number; sourceTrackId: number }>;
+  /**
+   * Bus insert sidechain bindings (replayed after lanes/buses/strips).
+   * `sourceKind` is a `SonareSidechainSourceKind` ordinal (0 track / 1 bus).
+   */
+  busSidechains?: Array<{
+    busId: number;
+    insertIndex: number;
+    sourceKind: number;
+    sourceId: number;
+  }>;
+  /** Master strip insert sidechain bindings. Same `sourceKind` convention. */
+  masterSidechains?: Array<{ insertIndex: number; sourceKind: number; sourceId: number }>;
 }
 
 export interface SonareEngineSyncCaptureMessage {
@@ -389,6 +553,13 @@ export interface SonareEngineSyncMasterStripEqBandMessage {
   bandJson: string;
 }
 
+export interface SonareEngineSyncBusStripEqBandMessage {
+  type: 'syncBusStripEqBand';
+  busId: number;
+  bandIndex: number;
+  bandJson: string;
+}
+
 export interface SonareEngineSyncTrackStripInsertBypassedMessage {
   type: 'syncTrackStripInsertBypassed';
   trackId: number;
@@ -427,6 +598,14 @@ export interface SonareEngineSyncBusStripInsertParamByNameMessage {
   value: number;
 }
 
+export interface SonareEngineSyncBusStripInsertBypassedMessage {
+  type: 'syncBusStripInsertBypassed';
+  busId: number;
+  insertIndex: number;
+  bypassed: boolean;
+  resetOnBypass: boolean;
+}
+
 export interface SonareEngineSyncTrackStripPanMessage {
   type: 'syncTrackStripPan';
   trackId: number;
@@ -452,6 +631,31 @@ export interface SonareEngineSyncTrackStripDualPanMessage {
   rightPan: number;
 }
 
+export interface SonareEngineSyncBusStripPanMessage {
+  type: 'syncBusStripPan';
+  busId: number;
+  pan: number;
+}
+
+export interface SonareEngineSyncBusStripPanLawMessage {
+  type: 'syncBusStripPanLaw';
+  busId: number;
+  panLaw: number;
+}
+
+export interface SonareEngineSyncBusStripPanModeMessage {
+  type: 'syncBusStripPanMode';
+  busId: number;
+  panMode: number;
+}
+
+export interface SonareEngineSyncBusStripDualPanMessage {
+  type: 'syncBusStripDualPan';
+  busId: number;
+  leftPan: number;
+  rightPan: number;
+}
+
 export interface SonareEngineSyncTrackStripChannelDelaySamplesMessage {
   type: 'syncTrackStripChannelDelaySamples';
   trackId: number;
@@ -478,6 +682,8 @@ export interface SonareEngineSyncSf2InstrumentMessage {
     gain?: number;
     polyphony?: number;
     preferModelForModeledFamilies?: boolean;
+    clearBankRig?: boolean;
+    gsEfxRealization?: 'modern' | 'classic';
   };
 }
 
@@ -520,6 +726,22 @@ export interface SonareEngineSyncMidiUmpMessage {
   renderFrame: number;
 }
 
+/**
+ * One of the three per-note expression dimensions, addressed to a destination.
+ * `data0`/`data1` carry the dimension's own payload the way the live-input
+ * message beside this one does: bend14 / 0, pressure / 0, or note / pressure.
+ * A bend is 14-bit, which is why these do not ride the 7-bit CC message.
+ */
+export interface SonareEngineSyncMidiExpressionMessage {
+  type: 'syncMidiPitchBend' | 'syncMidiChannelPressure' | 'syncMidiPolyPressure';
+  destinationId: number;
+  group: number;
+  channel: number;
+  data0: number;
+  data1: number;
+  renderFrame: number;
+}
+
 export interface SonareEngineSyncMidiSysexMessage {
   type: 'syncMidiSysex';
   destinationId: number;
@@ -558,7 +780,13 @@ export interface SonareEngineSyncMidiCcBindingMessage {
 }
 
 export interface SonareEngineSyncMidiInputEventMessage {
-  type: 'syncMidiInputNoteOn' | 'syncMidiInputNoteOff' | 'syncMidiInputCc';
+  type:
+    | 'syncMidiInputNoteOn'
+    | 'syncMidiInputNoteOff'
+    | 'syncMidiInputCc'
+    | 'syncMidiInputPitchBend'
+    | 'syncMidiInputChannelPressure'
+    | 'syncMidiInputPolyPressure';
   group: number;
   channel: number;
   data0: number;
@@ -584,6 +812,8 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncClipPageProviderMessage
   | SonareEngineSyncClipPageMessage
   | SonareEngineSyncClipPageClearMessage
+  | SonareEngineSyncClipPagePrefetchFramesMessage
+  | SonareEngineSyncWarpVoiceCapacityMessage
   | SonareEngineSyncClipPageCommitMessage
   | SonareEngineSyncClipPageDestroyMessage
   | SonareEngineSyncMidiClipsMessage
@@ -596,15 +826,21 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncCaptureMessage
   | SonareEngineSyncTrackStripEqBandMessage
   | SonareEngineSyncMasterStripEqBandMessage
+  | SonareEngineSyncBusStripEqBandMessage
   | SonareEngineSyncTrackStripInsertBypassedMessage
   | SonareEngineSyncMasterStripInsertBypassedMessage
   | SonareEngineSyncTrackStripInsertParamByNameMessage
   | SonareEngineSyncMasterStripInsertParamByNameMessage
   | SonareEngineSyncBusStripInsertParamByNameMessage
+  | SonareEngineSyncBusStripInsertBypassedMessage
   | SonareEngineSyncTrackStripPanMessage
   | SonareEngineSyncTrackStripPanLawMessage
   | SonareEngineSyncTrackStripPanModeMessage
   | SonareEngineSyncTrackStripDualPanMessage
+  | SonareEngineSyncBusStripPanMessage
+  | SonareEngineSyncBusStripPanLawMessage
+  | SonareEngineSyncBusStripPanModeMessage
+  | SonareEngineSyncBusStripDualPanMessage
   | SonareEngineSyncTrackStripChannelDelaySamplesMessage
   | SonareEngineSyncBuiltinInstrumentMessage
   | SonareEngineSyncSynthInstrumentMessage
@@ -614,6 +850,7 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncMidiNoteMessage
   | SonareEngineSyncMidiCcMessage
   | SonareEngineSyncMidiUmpMessage
+  | SonareEngineSyncMidiExpressionMessage
   | SonareEngineSyncMidiSysexMessage
   | SonareEngineSyncMidiPanicMessage
   | SonareEngineSyncMidiDestinationExternalMessage