@libraz/libsonare 1.3.0 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "type": "module",
   "packageManager": "yarn@4.15.0",
   "description": "Audio analysis library for music information retrieval",

package/src/effects_mastering.ts

@@ -376,6 +376,22 @@ export function masteringInsertNames(): string[] {
   ).masteringInsertNames();
 }
 
+/**
+ * Returns the camelCase parameter names a given insert / FX processor reads, for
+ * tooling/validation. Any key NOT in this list is silently ignored by the
+ * processor (and would be reported via {@link Mixer.sceneWarnings} when a scene
+ * carrying it is loaded). Band/sub-band processors enumerate their indexed
+ * `band{i}.<field>` keys. Returns an empty array for an unknown name (or one
+ * whose insert needs an unavailable build feature, e.g. FX).
+ *
+ * @param name - Insert processor name (see {@link masteringInsertNames}).
+ */
+export function masteringInsertParamNames(name: string): string[] {
+  return (
+    requireModule() as unknown as { masteringInsertParamNames: (name: string) => string[] }
+  ).masteringInsertParamNames(name);
+}
+
 export function masteringPairProcessorNames(): PairProcessor[] {
   return requireModule().masteringPairProcessorNames() as PairProcessor[];
 }

package/src/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Numeric error codes carried by a {@link SonareError}. Mirrors the C ABI
+ * `SonareError` enum (and the Node / Python surfaces), so the same failure
+ * reports the same numeric code on every binding.
+ */
+export enum ErrorCode {
+  Ok = 0,
+  FileNotFound = 1,
+  InvalidFormat = 2,
+  DecodeFailed = 3,
+  InvalidParameter = 4,
+  OutOfMemory = 5,
+  NotSupported = 6,
+  InvalidState = 7,
+  Unknown = 99,
+}
+
+/**
+ * Error thrown by libsonare on a native (C++) failure. Carries a numeric
+ * {@link ErrorCode} `code` plus its canonical `codeName`, so callers can branch
+ * on the cause instead of matching message text.
+ */
+export class SonareError extends Error {
+  /** Numeric error code, equal to an {@link ErrorCode} value. */
+  readonly code: number;
+  /** Canonical name of `code`, e.g. `'InvalidParameter'`. */
+  readonly codeName: string;
+
+  constructor(code: number, codeName: string, message: string) {
+    super(message);
+    this.name = 'SonareError';
+    this.code = code;
+    this.codeName = codeName;
+  }
+}
+
+/** Type guard: whether a caught value is a libsonare {@link SonareError}. */
+export function isSonareError(value: unknown): value is SonareError {
+  return (
+    value instanceof Error &&
+    (value as { name?: unknown }).name === 'SonareError' &&
+    typeof (value as { code?: unknown }).code === 'number'
+  );
+}

package/src/index.ts

@@ -67,6 +67,7 @@ export {
   masteringDynamicsGate,
   masteringDynamicsTransientShaper,
   masteringInsertNames,
+  masteringInsertParamNames,
   masteringPairAnalysisNames,
   masteringPairAnalyze,
   masteringPairProcess,
@@ -98,6 +99,7 @@ export {
   voiceChange,
   voiceChangeRealtime,
 } from './effects_mastering';
+export { ErrorCode, isSonareError, SonareError } from './errors';
 export type { MelodyOptions } from './feature_music';
 export {
   amplitudeToDb,

package/src/live_audio.ts

@@ -16,11 +16,13 @@ export async function bindMicrophoneInput(
   engine: SonareRealtimeEngineNode | AudioWorkletNode,
   options: BindMicrophoneInputOptions = {},
 ): Promise<MicrophoneInputBinding> {
+  const { stream: providedStream, stopTracksOnClose = true, ...constraints } = options;
   const stream =
-    options.stream ??
+    providedStream ??
     (await navigator.mediaDevices.getUserMedia({
-      audio: options.audio ?? true,
-      video: false,
+      ...constraints,
+      audio: constraints.audio ?? true,
+      video: constraints.video ?? false,
     }));
   const source = context.createMediaStreamSource(stream);
   const node = 'node' in engine ? engine.node : engine;
@@ -35,7 +37,7 @@ export async function bindMicrophoneInput(
       }
       closed = true;
       source.disconnect();
-      if (options.stopTracksOnClose !== false) {
+      if (stopTracksOnClose) {
         for (const track of stream.getAudioTracks()) {
           track.stop();
         }

package/src/mixer.ts

@@ -76,6 +76,17 @@ export class Mixer {
     this.mixer.compile();
   }
 
+  /**
+   * Non-fatal warnings captured when this mixer was built from scene JSON: one
+   * entry per channel-strip insert that was handed param keys it does not read
+   * (a likely typo, or a key meant for a different processor). The scene still
+   * loaded; these keys simply took no effect. Empty when every key was consumed.
+   * Use {@link masteringInsertParamNames} to discover the keys an insert accepts.
+   */
+  sceneWarnings(): string[] {
+    return this.mixer.sceneWarnings();
+  }
+
   /**
    * Mix one block of per-strip stereo audio into the stereo master.
    *

package/src/module_state.ts

@@ -1,14 +1,125 @@
+import { ErrorCode, SonareError } from './errors';
 import type { SonareModule } from './sonare.js';
 
-let wasmModule: SonareModule | null = null;
+let wrappedModule: SonareModule | null = null;
+
+/**
+ * Shape of the structured info the native `sonareExceptionInfo(ptr)` returns.
+ */
+interface NativeExceptionInfo {
+  code: number;
+  codeName: string;
+  message: string;
+}
+
+/**
+ * Recover the native exception-object pointer from a value thrown across the
+ * WASM boundary. emscripten surfaces a C++ throw in two shapes depending on the
+ * toolchain/exception mode:
+ *   - a raw pointer number (older / classic surfacing), or
+ *   - a `CppException` object exposing the pointer as `excPtr` (emscripten with
+ *     `-fexceptions`).
+ * Returns null when the thrown value is neither (a genuine JS error), so the
+ * caller rethrows it unchanged.
+ */
+function nativeExceptionPtr(error: unknown): number | null {
+  if (typeof error === 'number') {
+    return error;
+  }
+  if (error !== null && typeof error === 'object') {
+    const ptr = (error as { excPtr?: unknown }).excPtr;
+    if (typeof ptr === 'number') {
+      return ptr;
+    }
+  }
+  return null;
+}
+
+/**
+ * Turn a thrown native exception pointer into a {@link SonareError}. The bound
+ * `sonareExceptionInfo` decodes the pointer back into { code, codeName,
+ * message }.
+ */
+function makeSonareError(raw: SonareModule, thrown: number): SonareError {
+  let code: number = ErrorCode.Unknown;
+  let codeName = 'Unknown';
+  let message = `libsonare native exception (${thrown})`;
+  try {
+    const info = (
+      raw as unknown as { sonareExceptionInfo?: (ptr: number) => NativeExceptionInfo }
+    ).sonareExceptionInfo?.(thrown);
+    if (info) {
+      code = info.code ?? code;
+      codeName = info.codeName ?? codeName;
+      message = info.message || message;
+    }
+  } catch {
+    // Fall back to the generic message if decoding fails.
+  }
+  return new SonareError(code, codeName, message);
+}
+
+/**
+ * Wrap the embind module so a native C++ exception (which surfaces as a raw
+ * pointer number or a `CppException` carrying one) is rethrown as a
+ * {@link SonareError}. Only function-valued
+ * members are wrapped, and the wrapper is cached per member so repeated access
+ * stays cheap; non-function members (typed-array heap views, etc.) pass through
+ * unchanged. The dedicated realtime `sonare-rt` module is separate and is not
+ * affected by this wrapper.
+ */
+function wrapModuleErrors(raw: SonareModule): SonareModule {
+  const cache = new Map<PropertyKey, unknown>();
+  const convert = (error: unknown): never => {
+    const ptr = nativeExceptionPtr(error);
+    if (ptr !== null) {
+      throw makeSonareError(raw, ptr);
+    }
+    throw error;
+  };
+  return new Proxy(raw, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value !== 'function') {
+        return value;
+      }
+      const cached = cache.get(prop);
+      if (cached) {
+        return cached;
+      }
+      // Wrap as a Proxy (not a plain function) so embind class constructors
+      // invoked via `new module.Foo(...)` keep their `[[Construct]]` behaviour
+      // and prototype while still converting thrown native pointers.
+      const fn = value as (...a: unknown[]) => unknown;
+      const wrapped = new Proxy(fn, {
+        apply(t, thisArg, args) {
+          try {
+            return Reflect.apply(t, thisArg, args as unknown[]);
+          } catch (error) {
+            return convert(error);
+          }
+        },
+        construct(t, args, newTarget) {
+          try {
+            return Reflect.construct(t, args as unknown[], newTarget) as object;
+          } catch (error) {
+            return convert(error) as object;
+          }
+        },
+      });
+      cache.set(prop, wrapped);
+      return wrapped;
+    },
+  }) as SonareModule;
+}
 
 export function setSonareModule(module: SonareModule): void {
-  wasmModule = module;
+  wrappedModule = wrapModuleErrors(module);
 }
 
 export function getSonareModule(): SonareModule {
-  if (!wasmModule) {
+  if (!wrappedModule) {
     throw new Error('Module not initialized. Call init() first.');
   }
-  return wasmModule;
+  return wrappedModule;
 }

package/src/opfs_clip_pages.ts

@@ -55,12 +55,22 @@ self.onmessage = async (event) => {
       const frames = Math.min(pageFrames, numSamples - startFrame);
       const frameBytes = numChannels * 4;
       const bytes = new Uint8Array(frames * frameBytes);
-      const bytesRead = access.read(bytes, { at: dataOffsetBytes + startFrame * frameBytes });
-      const framesRead = Math.floor(bytesRead / frameBytes);
-      if (framesRead <= 0) {
+      let bytesReadTotal = 0;
+      const readOffset = dataOffsetBytes + startFrame * frameBytes;
+      while (bytesReadTotal < bytes.byteLength) {
+        const bytesRead = access.read(bytes.subarray(bytesReadTotal), {
+          at: readOffset + bytesReadTotal,
+        });
+        if (bytesRead <= 0) {
+          break;
+        }
+        bytesReadTotal += bytesRead;
+      }
+      if (bytesReadTotal !== bytes.byteLength || bytesReadTotal % frameBytes !== 0) {
         self.postMessage({ type: 'sonare:clip-page', requestId, pageIndex, ok: false });
         return;
       }
+      const framesRead = bytesReadTotal / frameBytes;
       const view = new DataView(bytes.buffer, 0, framesRead * frameBytes);
       const channelBuffers = Array.from({ length: numChannels }, () => new ArrayBuffer(framesRead * 4));
       for (let ch = 0; ch < numChannels; ++ch) {
@@ -137,7 +147,12 @@ export function createOpfsClipPageProvider(
       entry.resolve(false);
       return;
     }
-    provider.supply(response.pageIndex, channels);
+    try {
+      provider.supply(response.pageIndex, channels);
+    } catch {
+      entry.resolve(false);
+      return;
+    }
     entry.resolve(true);
   };
   worker.addEventListener('message', onMessage as EventListener);

package/src/sonare.js.d.ts

@@ -1845,6 +1845,11 @@ export interface SonareModule {
 
   // Mixing - scene-based Mixer
   createMixerFromSceneJson: (json: string, sampleRate: number, blockSize: number) => WasmMixer;
+
+  // Decodes a thrown native exception-object pointer (emscripten classic EH
+  // surfaces a C++ throw as the raw pointer number) into a structured error.
+  // Consumed by the module-error wrapper in module_state.ts.
+  sonareExceptionInfo: (ptr: number) => { code: number; codeName: string; message: string };
 }
 
 export interface WasmStreamingMasteringChain {
@@ -1947,6 +1952,7 @@ export interface WasmMixer {
   outputRightView: () => Float32Array;
   processPreparedStereo: (numSamples: number) => void;
   stripCount: () => number;
+  sceneWarnings: () => string[];
   scheduleInsertAutomation: (
     stripIndex: number,
     insertIndex: number,

package/src/web_midi.ts

@@ -105,9 +105,8 @@ export async function bindWebMidi(
   engine: RealtimeEngine,
   options: BindWebMidiOptions = {},
 ): Promise<WebMidiBinding> {
-  const requestMIDIAccess = (globalThis.navigator as NavigatorWithMidi | undefined)
-    ?.requestMIDIAccess;
-  if (typeof requestMIDIAccess !== 'function') {
+  const navigatorWithMidi = globalThis.navigator as NavigatorWithMidi | undefined;
+  if (typeof navigatorWithMidi?.requestMIDIAccess !== 'function') {
     throw new Error('Web MIDI is not available in this environment');
   }
 
@@ -115,7 +114,9 @@ export async function bindWebMidi(
   assertNibble('bindWebMidi', group, 'group');
   const destinationId = options.destinationId ?? 0;
   const selectedIds = new Set(options.inputIds ?? []);
-  const access = await requestMIDIAccess({
+  // Invoke through the navigator so the browser's native method keeps its
+  // required `this` binding (detached calls throw "Illegal invocation").
+  const access = await navigatorWithMidi.requestMIDIAccess({
     sysex: options.sysex ?? false,
     software: options.software ?? true,
   });
@@ -154,9 +155,7 @@ export async function bindWebMidi(
         runningStatus,
         options.timestampToSamples,
       );
-      if (status !== 0) {
-        runningStatus = status;
-      }
+      runningStatus = status;
     };
     if (input.addEventListener) {
       input.addEventListener('midimessage', listener);
@@ -268,12 +267,12 @@ function dispatchMidiMessage(
   const message = status & 0xf0;
   const channel = status & 0x0f;
   if (message < 0x80 || message > 0xe0) {
-    return status;
+    return status >= 0xf8 ? runningStatus : 0;
   }
 
   const a = readU7(data, offset);
   const b = readU7(data, offset + 1);
-  if (a < 0) {
+  if (a < 0 || b < 0) {
     return status;
   }
 
@@ -282,9 +281,9 @@ function dispatchMidiMessage(
     : 0;
 
   if (message === 0x80) {
-    engine.pushMidiInputNoteOff(group, channel, a, b < 0 ? 0 : b, portTimeSamples);
+    engine.pushMidiInputNoteOff(group, channel, a, b, portTimeSamples);
   } else if (message === 0x90) {
-    if ((b < 0 ? 0 : b) === 0) {
+    if (b === 0) {
       engine.pushMidiInputNoteOff(group, channel, a, 0, portTimeSamples);
     } else {
       engine.pushMidiInputNoteOn(group, channel, a, b, portTimeSamples);