@libraz/libsonare 1.3.2 → 1.4.0

package/src/sonare.js.d.ts

@@ -2,8 +2,11 @@
  * Type declarations for the Emscripten-generated WASM module with embind
  */
 
+import type { SpectralRegionOp, SurroundPan } from './public_types';
+
 export interface SonareModuleOptions {
   locateFile?: (path: string, prefix: string) => string;
+  wasmBinary?: ArrayBuffer | Uint8Array;
   onRuntimeInitialized?: () => void;
   print?: (text: string) => void;
   printErr?: (text: string) => void;
@@ -518,6 +521,7 @@ export interface WasmMixResult {
 
 export interface WasmEngineClip {
   id?: number;
+  trackId?: number;
   channels?: Float32Array[];
   startPpq: number;
   lengthSamples?: number;
@@ -531,6 +535,33 @@ export interface WasmEngineClip {
   pageProvider?: number | { readonly id: number };
 }
 
+export interface WasmEngineTrackSend {
+  busId: number;
+  levelDb?: number;
+  enabled?: boolean;
+}
+
+export interface WasmEngineTrackLane {
+  trackId: number;
+  sends?: WasmEngineTrackSend[];
+  /**
+   * Bus the lane's post-fader output sums into instead of the master mix
+   * (group/folder routing); 0 or absent keeps the lane on the master mix.
+   */
+  outputBusId?: number;
+  /**
+   * Input channel layout of the source feeding this lane (`SonareChannelLayout`:
+   * 0 mono, 1 stereo, 2 5.1, 3 7.1). Absent defaults to stereo.
+   */
+  sourceChannelLayout?: number;
+}
+
+export interface WasmEngineBus {
+  busId: number;
+  gainDb?: number;
+  channelLayout?: number;
+}
+
 export interface WasmClipPageRequest {
   clipId: number;
   channel: number;
@@ -558,6 +589,18 @@ export interface WasmEngineMarker {
   id: number;
   ppq: number;
   name?: string;
+  kind?: number;
+  keyFifths?: number;
+  keyMinor?: boolean;
+}
+
+export interface WasmProjectMarker {
+  id: number;
+  ppq: number;
+  name?: string;
+  kind?: number;
+  keyFifths?: number;
+  keyMinor?: boolean;
 }
 
 export interface WasmEngineMetronomeConfig {
@@ -628,6 +671,38 @@ export interface WasmEngineMeterTelemetry {
   droppedRecords: number;
 }
 
+export interface WasmEngineMeterTelemetryWide {
+  targetId: number;
+  renderFrame: number;
+  seq: number;
+  channelCount: number;
+  peakDb: number[];
+  rmsDb: number[];
+  truePeakDb: number[];
+  maxTruePeakDb: number;
+  correlation: number;
+  monoCompatWidth: number;
+  momentaryLufs: number;
+  shortTermLufs: number;
+  integratedLufs: number;
+  gainReductionDb: number;
+  droppedRecords: number;
+}
+
+export interface WasmEngineScopeTelemetry {
+  targetId: number;
+  renderFrame: number;
+  seq: number;
+  droppedRecords: number;
+  bands: number[];
+  /**
+   * Goniometer/vectorscope sample points as `{ left, right }` objects. The
+   * Python surface exposes the same data as `(left, right)` tuples; this
+   * representation difference is intentional, the values match.
+   */
+  points: { left: number; right: number }[];
+}
+
 export interface WasmEngineCaptureStatus {
   capturedFrames: number;
   overflowCount: number;
@@ -696,6 +771,18 @@ export interface WasmEngineProcessWithMonitorResult {
   monitor: Float32Array[];
 }
 
+export interface WasmEngineTempoSegment {
+  startPpq: number;
+  bpm: number;
+  endBpm?: number;
+}
+
+export interface WasmEngineTimeSignatureSegment {
+  startPpq: number;
+  numerator: number;
+  denominator: number;
+}
+
 export interface WasmRealtimeEngine {
   prepare: (
     sampleRate: number,
@@ -705,13 +792,18 @@ export interface WasmRealtimeEngine {
   ) => void;
   setParameter: (paramId: number, value: number, renderFrame: number) => void;
   setParameterSmoothed: (paramId: number, value: number, renderFrame: number) => void;
+  setSoloMute: (laneIndex: number, solo: boolean, mute: boolean, renderFrame: number) => void;
   getTransportState: () => WasmEngineTransportState;
   play: (renderFrame: number) => void;
   stop: (renderFrame: number) => void;
   seekSample: (timelineSample: number, renderFrame: number) => void;
+  settleParameters: () => void;
   seekPpq: (ppq: number, renderFrame: number) => void;
   setTempo: (bpm: number) => void;
+  setTempoSegments: (segments: WasmEngineTempoSegment[]) => void;
   setTimeSignature: (numerator: number, denominator: number) => void;
+  setTimeSignatureSegments: (segments: WasmEngineTimeSignatureSegment[]) => void;
+  sampleAtPpq: (ppq: number) => number;
   setLoop: (startPpq: number, endPpq: number, enabled: boolean) => void;
   addParameter: (info: WasmEngineParameterInfo) => void;
   parameterCount: () => number;
@@ -733,6 +825,37 @@ export interface WasmRealtimeEngine {
   graphConnectionCount: () => number;
   setClips: (clips: WasmEngineClip[]) => void;
   clipCount: () => number;
+  setTrackLanes: (lanes: Array<number | WasmEngineTrackLane>) => void;
+  setLaneSidechain: (trackId: number, insertIndex: number, sourceTrackId: number) => void;
+  setTrackBuses: (buses: WasmEngineBus[]) => void;
+  setBusStripJson: (busId: number, sceneJson: string) => void;
+  setTrackStripJson: (trackId: number, sceneJson: string) => void;
+  setTrackStripEqBandJson: (trackId: number, bandIndex: number, bandJson: string) => void;
+  setTrackStripInsertBypassed: (
+    trackId: number,
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass: boolean,
+  ) => void;
+  setMasterStripJson: (sceneJson: string) => void;
+  setMasterStripEqBandJson: (bandIndex: number, bandJson: string) => void;
+  setMasterStripInsertBypassed: (
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass: boolean,
+  ) => void;
+  setTrackStripInsertParamByName: (
+    trackId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ) => void;
+  setMasterStripInsertParamByName: (insertIndex: number, paramName: string, value: number) => void;
+  setTrackStripPan: (trackId: number, pan: number) => void;
+  setTrackStripPanLaw: (trackId: number, panLaw: number) => void;
+  setTrackStripPanMode: (trackId: number, panMode: number) => void;
+  setTrackStripDualPan: (trackId: number, leftPan: number, rightPan: number) => void;
+  setTrackStripChannelDelaySamples: (trackId: number, delaySamples: number) => void;
   createClipPageProvider: (numChannels: number, numSamples: number, pageFrames: number) => number;
   supplyClipPage: (providerId: number, pageIndex: number, channels: Float32Array[]) => void;
   clearClipPage: (providerId: number, pageIndex: number) => void;
@@ -747,7 +870,11 @@ export interface WasmRealtimeEngine {
   resetCapture: () => void;
   captureStatus: () => WasmEngineCaptureStatus;
   capturedAudio: () => Float32Array[];
+  setMidiClips: (clips: readonly object[]) => void;
   setBuiltinInstrument: (destinationId: number, config: object) => void;
+  setSynthInstrument: (destinationId: number, patch: object | string) => void;
+  loadSoundFont: (data: Uint8Array) => void;
+  setSf2Instrument: (destinationId: number, config: object) => void;
   clearMidiInstrument: (destinationId: number) => void;
   midiInstrumentCount: () => number;
   bindMidiCc: (
@@ -759,6 +886,8 @@ export interface WasmRealtimeEngine {
   ) => void;
   clearMidiCcBindings: () => void;
   midiCcBindingCount: () => number;
+  setMidiFx: (destinationId: number, configJson: string) => void;
+  clearMidiFx: (destinationId: number) => void;
   setMidiInputSource: (destinationId: number) => void;
   clearMidiInputSource: () => void;
   midiInputPendingCount: () => number;
@@ -808,6 +937,7 @@ export interface WasmRealtimeEngine {
     renderFrame: number,
   ) => void;
   pushMidiPanic: (renderFrame: number) => void;
+  clearParameters: () => void;
   process: (channels: Float32Array[]) => Float32Array[];
   prepareChannels: (numChannels: number, maxFrames: number) => void;
   getChannelBuffer: (channel: number, numFrames: number) => Float32Array;
@@ -818,6 +948,9 @@ export interface WasmRealtimeEngine {
   freezeOffline: (options: WasmEngineFreezeOptions) => WasmEngineFreezeResult;
   drainTelemetry: (maxRecords: number) => WasmEngineTelemetry[];
   drainMeterTelemetry: (maxRecords: number) => WasmEngineMeterTelemetry[];
+  drainMeterTelemetryWide: (maxRecords: number) => WasmEngineMeterTelemetryWide[];
+  configureScopeTelemetry: (intervalFrames: number, bandCount: number) => number;
+  drainScopeTelemetry: (maxRecords: number) => WasmEngineScopeTelemetry[];
   delete: () => void;
 }
 
@@ -1390,6 +1523,12 @@ export interface SonareModule {
     options: Record<string, unknown>,
   ) => WasmMixResult;
   trim: (samples: Float32Array, sampleRate: number, thresholdDb: number) => Float32Array;
+  spectralEdit: (
+    samples: Float32Array,
+    sampleRate: number,
+    ops: SpectralRegionOp[],
+    options: Record<string, unknown>,
+  ) => Float32Array;
 
   // Features - Spectrogram
   stft: (
@@ -1974,6 +2113,7 @@ export interface WasmMixer {
   setChannelDelaySamples: (stripIndex: number, delaySamples: number) => void;
   setVcaOffsetDb: (stripIndex: number, offsetDb: number) => void;
   setDualPan: (stripIndex: number, leftPan: number, rightPan: number) => void;
+  setSurroundPan: (stripIndex: number, pan: SurroundPan) => void;
   addSend: (
     stripIndex: number,
     id: string,

package/src/stream_types.ts

@@ -75,6 +75,11 @@ export interface FrameBuffer {
   /** Number of mel bands; flat `mel` is `[nFrames * nMels]` row-major. */
   nMels: number;
   timestamps: Float32Array;
+  /**
+   * Mel spectrogram in LINEAR power (not dB) — the raw per-frame mel energies.
+   * The quantized read paths (`readFramesU8` / `readFramesI16`) convert to dB
+   * before packing, so their `mel` is dB-scaled; this float buffer is not.
+   */
   mel: Float32Array;
   chroma: Float32Array;
   onsetStrength: Float32Array;
@@ -109,6 +114,7 @@ export interface StreamFramesU8 {
   nFrames: number;
   nMels: number;
   timestamps: Float32Array;
+  /** Row-major `[nFrames * nMels]` mel in dB, quantized over `[melDbMin, melDbMax]`. */
   mel: Uint8Array;
   chroma: Uint8Array;
   onsetStrength: Uint8Array;
@@ -121,6 +127,7 @@ export interface StreamFramesI16 {
   nFrames: number;
   nMels: number;
   timestamps: Float32Array;
+  /** Row-major `[nFrames * nMels]` mel in dB, quantized over `[melDbMin, melDbMax]`. */
   mel: Int16Array;
   chroma: Int16Array;
   onsetStrength: Int16Array;

package/src/validation.ts

@@ -2,6 +2,13 @@
  * Per-call validation options accepted by guarded wrappers. Empty-buffer
  * checks are always performed; pass `{ validate: false }` to opt out of the
  * O(n) NaN/Inf scan on hot paths.
+ *
+ * `{ validate: false }` only skips this JS-side pre-scan (which raises a
+ * `RangeError` naming the exact offending index). It is NOT a way to push
+ * non-finite samples into the core: the native layer always re-validates the
+ * buffer (see `validate_offline_audio_input` in the C++ core), matching the C
+ * ABI / Node / Python surfaces, so an NaN/Inf buffer still throws — just with a
+ * generic native message instead of the indexed JS one.
  */
 export interface ValidateOptions {
   validate?: boolean;

package/src/web_midi.ts

@@ -93,6 +93,7 @@ export interface WebMidiBinding {
 type BoundInput = {
   input: MidiInputLike;
   listener: (event: MidiMessageEventLike) => void;
+  runningStatus: number;
 };
 
 export function isWebMidiAvailable(): boolean {
@@ -128,7 +129,6 @@ export async function bindWebMidi(
 
   const bound = new Map<string, BoundInput>();
   let closed = false;
-  let runningStatus = 0;
 
   const shouldBind = (input: MidiInputLike) =>
     input.state !== 'disconnected' && (selectedIds.size === 0 || selectedIds.has(input.id));
@@ -147,22 +147,26 @@ export async function bindWebMidi(
     if (bound.has(input.id) || !shouldBind(input)) {
       return;
     }
-    const listener = (event: MidiMessageEventLike) => {
-      const status = dispatchMidiMessage(
-        engine,
-        event,
-        group,
-        runningStatus,
-        options.timestampToSamples,
-      );
-      runningStatus = status;
+    const entry: BoundInput = {
+      input,
+      listener: (event: MidiMessageEventLike) => {
+        entry.runningStatus = dispatchMidiMessage(
+          engine,
+          event,
+          group,
+          entry.runningStatus,
+          options.timestampToSamples,
+        );
+      },
+      runningStatus: 0,
     };
+    const listener = entry.listener;
     if (input.addEventListener) {
       input.addEventListener('midimessage', listener);
     } else {
       input.onmidimessage = listener;
     }
-    bound.set(input.id, { input, listener });
+    bound.set(input.id, entry);
   };
 
   const unbindInput = (input: MidiInputLike) => {

package/src/worklet/audio_types.ts

@@ -0,0 +1,2 @@
+export type WorkletInput = readonly (readonly Float32Array[])[];
+export type WorkletOutput = Float32Array[][];

package/src/worklet/guards.ts

@@ -0,0 +1,146 @@
+import type {
+  SonareEngineCaptureRequestMessage,
+  SonareEngineCaptureResponseMessage,
+  SonareEngineSyncMessage,
+  SonareEngineTransportRequestMessage,
+  SonareEngineTransportResponseMessage,
+  SonareRealtimeVoiceChangerMessage,
+  SonareWorkletMessage,
+} from './messages';
+import {
+  isRecord,
+  type SonareEngineCommandRecord,
+  type SonareEngineTelemetryRecord,
+  type SonareWorkletMeterSnapshot,
+} from './protocol';
+
+export function isWorkletMessage(value: unknown): value is SonareWorkletMessage {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return false;
+  }
+  return (
+    value.type === 'scheduleInsertAutomation' ||
+    value.type === 'setMeterInterval' ||
+    value.type === 'destroy'
+  );
+}
+
+export function isEngineCommandRecord(value: unknown): value is SonareEngineCommandRecord {
+  return isRecord(value) && typeof value.type === 'number';
+}
+
+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 === '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 === '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 === 'syncMidiNoteOn' ||
+    value.type === 'syncMidiNoteOff' ||
+    value.type === 'syncMidiCc' ||
+    value.type === 'syncMidiPanic'
+  );
+}
+
+export function isEngineCaptureRequestMessage(
+  value: unknown,
+): value is SonareEngineCaptureRequestMessage {
+  return (
+    isRecord(value) &&
+    value.type === 'captureRequest' &&
+    typeof value.requestId === 'number' &&
+    (value.op === 'status' || value.op === 'read' || value.op === 'reset')
+  );
+}
+
+export function isEngineCaptureResponseMessage(
+  value: unknown,
+): value is SonareEngineCaptureResponseMessage {
+  return (
+    isRecord(value) &&
+    value.type === 'captureResponse' &&
+    typeof value.requestId === 'number' &&
+    typeof value.ok === 'boolean'
+  );
+}
+
+export function isEngineTransportRequestMessage(
+  value: unknown,
+): value is SonareEngineTransportRequestMessage {
+  return (
+    isRecord(value) &&
+    value.type === 'transportRequest' &&
+    typeof value.requestId === 'number' &&
+    value.op === 'state'
+  );
+}
+
+export function isEngineTransportResponseMessage(
+  value: unknown,
+): value is SonareEngineTransportResponseMessage {
+  return (
+    isRecord(value) &&
+    value.type === 'transportResponse' &&
+    typeof value.requestId === 'number' &&
+    typeof value.ok === 'boolean'
+  );
+}
+
+export function isRealtimeVoiceChangerMessage(
+  value: unknown,
+): value is SonareRealtimeVoiceChangerMessage {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return false;
+  }
+  return value.type === 'setConfig' || value.type === 'reset' || value.type === 'destroy';
+}
+
+export function isEngineTelemetryRecord(value: unknown): value is SonareEngineTelemetryRecord {
+  return (
+    isRecord(value) &&
+    typeof value.type === 'number' &&
+    typeof value.error === 'number' &&
+    typeof value.renderFrame === 'number' &&
+    typeof value.timelineSample === 'number' &&
+    typeof value.audibleTimelineSample === 'number' &&
+    typeof value.graphLatencySamplesQ8 === 'number' &&
+    typeof value.value === 'number'
+  );
+}
+
+export function isMeterSnapshot(value: unknown): value is SonareWorkletMeterSnapshot {
+  return (
+    isRecord(value) &&
+    value.type === 'meter' &&
+    typeof value.frame === 'number' &&
+    typeof value.peakDbL === 'number' &&
+    typeof value.peakDbR === 'number' &&
+    typeof value.rmsDbL === 'number' &&
+    typeof value.rmsDbR === 'number' &&
+    typeof value.correlation === 'number' &&
+    (typeof value.targetId === 'number' || value.targetId === undefined)
+  );
+}