@libraz/libsonare 1.3.1 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "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,
@@ -399,6 +401,7 @@ export type {
   EngineAutomationPoint,
   EngineBounceOptions,
   EngineBounceResult,
+  EngineBus,
   EngineCapabilities,
   EngineCaptureStatus,
   EngineClip,
@@ -408,8 +411,14 @@ export type {
   EngineMarker,
   EngineMeterTelemetry,
   EngineMetronomeConfig,
+  EngineMidiClipSchedule,
+  EngineMidiEvent,
   EngineParameterInfo,
   EngineTelemetry,
+  EngineTempoSegment,
+  EngineTimeSignatureSegment,
+  EngineTrackLane,
+  EngineTrackSend,
   EngineTransportState,
   MidiCcBindOptions,
 } from './realtime_engine';
@@ -482,6 +491,11 @@ let initPromise: Promise<void> | null = null;
  */
 export async function init(options?: {
   locateFile?: (path: string, prefix: string) => string;
+  wasmBinary?: ArrayBuffer | Uint8Array;
+  moduleFactory?: (options?: {
+    locateFile?: (path: string, prefix: string) => string;
+    wasmBinary?: ArrayBuffer | Uint8Array;
+  }) => Promise<SonareModule>;
 }): Promise<void> {
   if (module) {
     return;
@@ -493,7 +507,7 @@ export async function init(options?: {
 
   initPromise = (async () => {
     try {
-      const createModule = (await import('./sonare.js')).default;
+      const createModule = options?.moduleFactory ?? (await import('./sonare.js')).default;
       module = await createModule(options);
       setSonareModule(module);
     } catch (error) {

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,190 @@
+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 objectCache = new WeakMap<object, unknown>();
+  const convert = (error: unknown): never => {
+    const ptr = nativeExceptionPtr(error);
+    if (ptr !== null) {
+      throw makeSonareError(raw, ptr);
+    }
+    throw error;
+  };
+
+  const wrapNativeObject = (value: unknown): unknown => {
+    if (value === null || typeof value !== 'object') {
+      return value;
+    }
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer || value instanceof Promise) {
+      return value;
+    }
+    const objectValue = value as object;
+    const cached = objectCache.get(objectValue);
+    if (cached) {
+      return cached;
+    }
+    const methodCache = new Map<PropertyKey, unknown>();
+    const wrapped = new Proxy(objectValue, {
+      get(target, prop, receiver) {
+        const member = Reflect.get(target, prop, receiver);
+        if (typeof member !== 'function') {
+          return member;
+        }
+        const cachedMethod = methodCache.get(prop);
+        if (cachedMethod) {
+          return cachedMethod;
+        }
+        const method = member as (...a: unknown[]) => unknown;
+        const wrappedMethod = (...args: unknown[]) => {
+          try {
+            return wrapNativeObject(Reflect.apply(method, target, args));
+          } catch (error) {
+            return convert(error);
+          }
+        };
+        methodCache.set(prop, wrappedMethod);
+        return wrappedMethod;
+      },
+    });
+    objectCache.set(objectValue, wrapped);
+    return wrapped;
+  };
+
+  const wrapFunction = (value: (...a: unknown[]) => unknown): unknown => {
+    const fnCache = new Map<PropertyKey, unknown>();
+    return new Proxy(value, {
+      get(target, prop, receiver) {
+        const member = Reflect.get(target, prop, receiver);
+        if (typeof member !== 'function') {
+          return member;
+        }
+        const cachedMember = fnCache.get(prop);
+        if (cachedMember) {
+          return cachedMember;
+        }
+        const fn = member as (...a: unknown[]) => unknown;
+        const wrappedMember = (...args: unknown[]) => {
+          try {
+            return wrapNativeObject(Reflect.apply(fn, target, args));
+          } catch (error) {
+            return convert(error);
+          }
+        };
+        fnCache.set(prop, wrappedMember);
+        return wrappedMember;
+      },
+      apply(t, thisArg, args) {
+        try {
+          return wrapNativeObject(Reflect.apply(t, thisArg, args as unknown[]));
+        } catch (error) {
+          return convert(error);
+        }
+      },
+      construct(t, args, newTarget) {
+        try {
+          return wrapNativeObject(Reflect.construct(t, args as unknown[], newTarget));
+        } catch (error) {
+          return convert(error) as object;
+        }
+      },
+    });
+  };
+
+  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 wrapped = wrapFunction(value as (...a: unknown[]) => unknown);
+      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

@@ -29,10 +29,25 @@ interface PageResponse {
 }
 
 export const opfsClipPageWorkerSource = `
+const sonareClipPageReadQueues = new Map();
+
+function sonareEnqueueClipPageRead(key, task) {
+  const previous = sonareClipPageReadQueues.get(key) || Promise.resolve();
+  const next = previous.catch(() => undefined).then(task);
+  const queued = next.finally(() => {
+    if (sonareClipPageReadQueues.get(key) === queued) {
+      sonareClipPageReadQueues.delete(key);
+    }
+  });
+  sonareClipPageReadQueues.set(key, queued);
+  return next;
+}
+
 self.onmessage = async (event) => {
   const message = event.data;
   if (!message || message.type !== 'sonare:read-clip-page') return;
   const { requestId, path, pageIndex, numChannels, numSamples, pageFrames, dataOffsetBytes = 0 } = message;
+  await sonareEnqueueClipPageRead(String(path), async () => {
   try {
     if (pageIndex < 0) {
       self.postMessage({ type: 'sonare:clip-page', requestId, pageIndex, ok: false });
@@ -95,6 +110,7 @@ self.onmessage = async (event) => {
       error: error instanceof Error ? error.message : String(error),
     });
   }
+  });
 };
 `;
 
@@ -119,6 +135,7 @@ export function createOpfsClipPageProvider(
   const ownsWorker = options.worker === undefined || options.terminateWorkerOnClose === true;
   let nextRequestId = 1;
   let closed = false;
+  let readQueue: Promise<void> = Promise.resolve();
   const pending = new Map<
     number,
     { resolve: (value: boolean) => void; reject: (reason: unknown) => void }
@@ -165,15 +182,32 @@ export function createOpfsClipPageProvider(
     const promise = new Promise<boolean>((resolve, reject) => {
       pending.set(requestId, { resolve, reject });
     });
-    worker.postMessage({
-      type: 'sonare:read-clip-page',
-      requestId,
-      path: options.path,
-      pageIndex,
-      numChannels: options.numChannels,
-      numSamples: options.numSamples,
-      pageFrames: options.pageFrames,
-      dataOffsetBytes: options.dataOffsetBytes ?? 0,
+    readQueue = readQueue
+      .catch(() => undefined)
+      .then(() => {
+        if (closed) {
+          const entry = pending.get(requestId);
+          pending.delete(requestId);
+          entry?.reject(new Error('OpfsClipPageProvider is closed'));
+          return;
+        }
+        worker.postMessage({
+          type: 'sonare:read-clip-page',
+          requestId,
+          path: options.path,
+          pageIndex,
+          numChannels: options.numChannels,
+          numSamples: options.numSamples,
+          pageFrames: options.pageFrames,
+          dataOffsetBytes: options.dataOffsetBytes ?? 0,
+        });
+        return promise.then(
+          () => undefined,
+          () => undefined,
+        );
+      });
+    readQueue.catch(() => {
+      // The per-request promise carries the user-visible failure.
     });
     return promise;
   };