@libraz/libsonare 1.3.1 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.3.1",
+  "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/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/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,