@libraz/libsonare 1.5.5 → 1.7.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.5.5",
+  "version": "1.7.0",
   "type": "module",
-  "packageManager": "yarn@4.15.0",
+  "packageManager": "yarn@4.18.0",
   "description": "Audio analysis, mastering, mixing, and MIDI synthesis in WebAssembly",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,11 +11,21 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./analysis": {
+      "types": "./dist/analysis.d.ts",
+      "import": "./dist/analysis.js"
+    },
     "./worklet": {
       "types": "./dist/worklet.d.ts",
       "import": "./dist/worklet.js"
     },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    },
     "./wasm": "./dist/sonare.wasm",
+    "./schemas/realtime-voice-changer-preset.schema.json": "./dist/schemas/realtime-voice-changer-preset.schema.json",
+    "./schemas/realtime-voice-changer-preset-pack.schema.json": "./dist/schemas/realtime-voice-changer-preset-pack.schema.json",
     "./package.json": "./package.json"
   },
   "files": [
@@ -25,19 +35,24 @@
   "sideEffects": false,
   "scripts": {
     "build": "yarn build:wasm && yarn build:js",
-    "build:wasm": "mkdir -p build-wasm/em-cache && EM_CACHE=$PWD/build-wasm/em-cache emcmake cmake -S ../.. -B build-wasm -DBUILD_WASM=ON -DBUILD_MASTERING=ON -DCMAKE_BUILD_TYPE=Release && EM_CACHE=$PWD/build-wasm/em-cache cmake --build build-wasm",
+    "build:wasm": "yarn build:wasm:full && yarn build:wasm:analysis",
+    "build:wasm:full": "mkdir -p build-wasm/em-cache && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm/em-cache emcmake cmake -S ../.. -B build-wasm -DBUILD_WASM=ON -DSONARE_WASM_ANALYSIS_ONLY=OFF -DSONARE_WASM_OUTPUT_NAME=sonare -DBUILD_MASTERING=ON -DBUILD_MIXING=ON -DBUILD_GRAPH=ON -DBUILD_FX=ON -DBUILD_ACOUSTIC_SIM=ON -DBUILD_PITCH_EDITOR=ON -DBUILD_VOICE_CHANGER=ON -DBUILD_ARRANGEMENT=ON -DBUILD_ASSIST=ON -DCMAKE_BUILD_TYPE=Release && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm/em-cache cmake --build build-wasm",
+    "build:wasm:analysis": "mkdir -p build-wasm-analysis/em-cache && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm-analysis/em-cache emcmake cmake -S ../.. -B build-wasm-analysis -DBUILD_WASM=ON -DSONARE_WASM_ANALYSIS_ONLY=ON -DSONARE_WASM_OUTPUT_NAME=sonare-analysis -DBUILD_MASTERING=OFF -DBUILD_MIXING=OFF -DBUILD_GRAPH=OFF -DBUILD_FX=OFF -DBUILD_ACOUSTIC_SIM=OFF -DBUILD_VOICE_CHANGER=OFF -DBUILD_ARRANGEMENT=OFF -DBUILD_ASSIST=OFF -DCMAKE_BUILD_TYPE=Release && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm-analysis/em-cache cmake --build build-wasm-analysis --target sonare",
+    "check:wasm-size": "python3 ../../tools/check_wasm_size.py --baseline wasm-size-budget.json --artifact sonare.wasm=dist/sonare.wasm --artifact sonare-analysis.wasm=dist/sonare-analysis.wasm",
     "bench:wasm:isp": "mkdir -p build-wasm-bench/em-cache /tmp/libsonare-wasm-bench && EM_CACHE=$PWD/build-wasm-bench/em-cache emcmake cmake -S ../.. -B build-wasm-bench -DBUILD_WASM=ON -DBUILD_MASTERING=ON -DBUILD_BENCH=ON -DBUILD_TESTING=OFF -DBUILD_CLI=OFF -DCMAKE_BUILD_TYPE=Release && EM_CACHE=$PWD/build-wasm-bench/em-cache cmake --build build-wasm-bench --target sonare_mastering_isp_bench && cp build-wasm-bench/bin/sonare_mastering_isp_bench.js /tmp/libsonare-wasm-bench/sonare_mastering_isp_bench.cjs && cp build-wasm-bench/bin/sonare_mastering_isp_bench.wasm /tmp/libsonare-wasm-bench/sonare_mastering_isp_bench.wasm && node /tmp/libsonare-wasm-bench/sonare_mastering_isp_bench.cjs",
     "bench:wasm:phase-vocoder": "mkdir -p build-wasm-bench/em-cache /tmp/libsonare-wasm-bench && EM_CACHE=$PWD/build-wasm-bench/em-cache emcmake cmake -S ../.. -B build-wasm-bench -DBUILD_WASM=ON -DBUILD_BENCH=ON -DBUILD_TESTING=OFF -DBUILD_CLI=OFF -DCMAKE_BUILD_TYPE=Release && EM_CACHE=$PWD/build-wasm-bench/em-cache cmake --build build-wasm-bench --target sonare_phase_vocoder_streaming_bench && cp build-wasm-bench/bin/sonare_phase_vocoder_streaming_bench.js /tmp/libsonare-wasm-bench/sonare_phase_vocoder_streaming_bench.cjs && cp build-wasm-bench/bin/sonare_phase_vocoder_streaming_bench.wasm /tmp/libsonare-wasm-bench/sonare_phase_vocoder_streaming_bench.wasm && node /tmp/libsonare-wasm-bench/sonare_phase_vocoder_streaming_bench.cjs",
-    "build:js": "tsup",
-    "clean": "rm -rf dist build-wasm LICENSE",
+    "build:js": "tsup && node scripts/copy-schemas.mjs",
+    "clean": "rm -rf dist build-wasm build-wasm-analysis LICENSE",
     "lint": "biome check src/ tests/",
     "lint:fix": "biome check --write src/ tests/",
     "format": "biome format --write src/ tests/",
     "test": "vitest run",
+    "test:types": "tsc --noEmit --ignoreConfig --strict --module ESNext --moduleResolution bundler --target ES2020 tests/typing/analysis-entry.ts tests/typing/worklet-capture-response.ts",
     "test:browser": "node scripts/audio-worklet-smoke.mjs",
-    "test:browser:audit": "node scripts/audit-boundary-smoke.mjs",
+    "test:browser:worker": "node scripts/offline-worker-smoke.mjs",
+    "test:browser:boundary": "node scripts/boundary-smoke.mjs",
     "test:watch": "vitest",
-    "prepublishOnly": "yarn clean && cp ../../LICENSE LICENSE && yarn build && yarn lint && yarn test"
+    "prepublishOnly": "yarn clean && cp ../../LICENSE LICENSE && yarn build && yarn lint && yarn test && yarn test:types"
   },
   "keywords": [
     "audio",
@@ -76,12 +91,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
+    "ajv": "^8.17.1",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"
-  },
-  "volta": {
-    "node": "22.22.3",
-    "yarn": "4.15.0"
   }
 }

package/src/_chain_config.ts

@@ -4,9 +4,9 @@ type ChainSection = { [key: string]: number | boolean | ChainSection | undefined
 
 /**
  * Flattens a nested {@link MasteringChainConfig} into the dot-notation
- * `{ "module.processor.param": value }` map the WASM core consumes. Internal
- * helper shared by the mastering-chain / master-audio entry points; mirrors the
- * Node facade so a nested config produces identical overrides on both surfaces.
+ * `{ "module.processor.param": value }` map the core consumes. Internal helper
+ * shared by the mastering-chain / master-audio entry points. The core owns
+ * legacy flat-key aliases, so this remains a structural flattening step.
  */
 export function flattenChainConfig(config: MasteringChainConfig): Record<string, number | boolean> {
   const out: Record<string, number | boolean> = {};
@@ -17,6 +17,8 @@ export function flattenChainConfig(config: MasteringChainConfig): Record<string,
         out[path] = value;
       } else if (value !== null && typeof value === 'object') {
         walk(value, path);
+      } else if (value !== undefined) {
+        throw new TypeError(`Mastering override '${path}' must be a number or boolean.`);
       }
     }
   };

package/src/analysis.ts

@@ -0,0 +1,137 @@
+/**
+ * Analysis and feature-extraction entry point for the smaller WASM binary.
+ *
+ * This entry intentionally omits mastering, mixing, realtime engines, Project,
+ * and other native-handle APIs. Import the package root when those surfaces are
+ * required.
+ */
+
+import { setSonareModule } from './module_state';
+import type { SonareCapabilities } from './public_types';
+import type { SonareModule } from './sonare.js';
+
+export { ErrorCode, isSonareError, SonareError } from './errors';
+export * from './feature_core';
+export * from './feature_music';
+export * from './feature_pitch';
+export * from './feature_resample';
+export * from './feature_spectral';
+export * from './feature_spectrogram';
+export * from './metering';
+export * from './public_types';
+export type {
+  AnalyzeBpmRequest,
+  AnalyzeDynamicsRequest,
+  AnalyzeImpulseResponseRequest,
+  AnalyzeRhythmRequest,
+  AnalyzeTimbreRequest,
+  AnalyzeWithProgressRequest,
+  BpmAnalysisResult,
+  BpmCandidate,
+  ChordFunctionalAnalysisRequest,
+  DetectAcousticRequest,
+  DetectChordsRequest,
+  DetectKeyRequest,
+  DynamicsAnalysisResult,
+  MusicAnalyzeOptions,
+  MusicAnalyzeRequest,
+  RhythmAnalysisResult,
+  SamplesRequest,
+  TimbreAnalysisResult,
+  TimbreFrame,
+} from './quick_analysis';
+export {
+  analyze,
+  analyzeBpm,
+  analyzeDynamics,
+  analyzeImpulseResponse,
+  analyzeRhythm,
+  analyzeTimbre,
+  analyzeWithProgress,
+  chordFunctionalAnalysis,
+  detectAcoustic,
+  detectBeats,
+  detectBpm,
+  detectChords,
+  detectDownbeats,
+  detectKey,
+  detectKeyCandidates,
+  detectOnsets,
+  hasFfmpegSupport,
+} from './quick_analysis';
+
+let module: SonareModule | null = null;
+let initPromise: Promise<void> | null = null;
+
+/** Initialize the analysis-only WASM module. */
+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;
+  }
+  if (initPromise) {
+    return initPromise;
+  }
+  initPromise = (async () => {
+    try {
+      const createModule = options?.moduleFactory ?? (await import('./sonare-analysis.js')).default;
+      module = await createModule(options);
+      setSonareModule(module);
+    } catch (error) {
+      initPromise = null;
+      throw error;
+    }
+  })();
+  return initPromise;
+}
+
+/** Whether this analysis entry has loaded its WASM module. */
+export function isInitialized(): boolean {
+  return module !== null;
+}
+
+/** Version reported by the loaded analysis WASM module. */
+export function version(): string {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  return module.version();
+}
+
+/** Build capabilities for the loaded analysis-only module. */
+export function capabilities(): SonareCapabilities {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  return module.capabilities();
+}
+
+/** Packed C-ABI version for compatibility checks. */
+export function abiVersion(): number {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  return module.abiVersion();
+}
+
+/** Realtime command-queue ABI version shared with the full entry. */
+export function engineAbiVersion(): number {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  return module.engineAbiVersion();
+}
+
+/** Voice-changer ABI version retained for cross-entry compatibility checks. */
+export function voiceChangerAbiVersion(): number {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  return module.voiceChangerAbiVersion();
+}

package/src/analysis_helpers.ts

@@ -1,3 +1,4 @@
+import { resolveEnumOrdinal } from './codes';
 import type {
   AnalysisResult,
   ChordAnalysisResult,
@@ -48,6 +49,37 @@ export function convertKeyCandidate(wasm: WasmKeyCandidateResult): KeyCandidate
   };
 }
 
+// Consolidated spelling -> ordinal tables, resolved through the same
+// resolveEnumOrdinal() primitive as panModeCode/panLawCode/etc. in ./codes.
+// An unmapped string or an out-of-range numeric ordinal throws RangeError
+// instead of silently resolving to `undefined` (which used to reach the WASM
+// layer as a mistyped argument) or passing an unvalidated raw number through.
+const KEY_MODE_VALUES: Readonly<Record<string, number>> = {
+  major: Mode.Major,
+  minor: Mode.Minor,
+  dorian: Mode.Dorian,
+  phrygian: Mode.Phrygian,
+  lydian: Mode.Lydian,
+  mixolydian: Mode.Mixolydian,
+  locrian: Mode.Locrian,
+};
+
+const KEY_PROFILE_VALUES: Readonly<Record<KeyProfileName, number>> = {
+  ks: KeyProfileValues.KrumhanslSchmuckler,
+  krumhansl: KeyProfileValues.KrumhanslSchmuckler,
+  temperley: KeyProfileValues.Temperley,
+  shaath: KeyProfileValues.Shaath,
+  keyfinder: KeyProfileValues.Shaath,
+  'faraldo-edmt': KeyProfileValues.FaraldoEDMT,
+  edmt: KeyProfileValues.FaraldoEDMT,
+  'faraldo-edma': KeyProfileValues.FaraldoEDMA,
+  edma: KeyProfileValues.FaraldoEDMA,
+  'faraldo-edmm': KeyProfileValues.FaraldoEDMM,
+  edmm: KeyProfileValues.FaraldoEDMM,
+  'bellman-budge': KeyProfileValues.BellmanBudge,
+  bellman: KeyProfileValues.BellmanBudge,
+};
+
 export function keyModeValues(modes: KeyDetectionOptions['modes'] | undefined): number[] {
   if (!modes) {
     return [];
@@ -66,41 +98,14 @@ export function keyModeValues(modes: KeyDetectionOptions['modes'] | undefined):
       Mode.Locrian,
     ];
   }
-  const names = {
-    major: Mode.Major,
-    minor: Mode.Minor,
-    dorian: Mode.Dorian,
-    phrygian: Mode.Phrygian,
-    lydian: Mode.Lydian,
-    mixolydian: Mode.Mixolydian,
-    locrian: Mode.Locrian,
-  } as const;
-  return modes.map((mode) => (typeof mode === 'number' ? mode : names[mode]));
+  return modes.map((mode) => resolveEnumOrdinal(mode, KEY_MODE_VALUES, 'key mode'));
 }
 
 export function keyProfileValue(profile: KeyDetectionOptions['profile'] | undefined): number {
   if (profile === undefined) {
     return -1;
   }
-  if (typeof profile === 'number') {
-    return profile;
-  }
-  const names: Record<KeyProfileName, number> = {
-    ks: KeyProfileValues.KrumhanslSchmuckler,
-    krumhansl: KeyProfileValues.KrumhanslSchmuckler,
-    temperley: KeyProfileValues.Temperley,
-    shaath: KeyProfileValues.Shaath,
-    keyfinder: KeyProfileValues.Shaath,
-    'faraldo-edmt': KeyProfileValues.FaraldoEDMT,
-    edmt: KeyProfileValues.FaraldoEDMT,
-    'faraldo-edma': KeyProfileValues.FaraldoEDMA,
-    edma: KeyProfileValues.FaraldoEDMA,
-    'faraldo-edmm': KeyProfileValues.FaraldoEDMM,
-    edmm: KeyProfileValues.FaraldoEDMM,
-    'bellman-budge': KeyProfileValues.BellmanBudge,
-    bellman: KeyProfileValues.BellmanBudge,
-  };
-  return names[profile];
+  return resolveEnumOrdinal(profile, KEY_PROFILE_VALUES, 'key profile');
 }
 
 export function convertChordAnalysisResult(wasm: WasmChordAnalysisResult): ChordAnalysisResult {
@@ -137,6 +142,11 @@ export function convertAnalysisResult(wasm: WasmAnalysisResult): AnalysisResult
   return {
     bpm: wasm.bpm,
     bpmConfidence: wasm.bpmConfidence,
+    bpmCandidates: wasm.bpmCandidates.map((candidate) => ({
+      value: candidate.value,
+      confidence: candidate.confidence,
+      relation: candidate.relation,
+    })),
     key: {
       root: wasm.key.root as PitchClass,
       mode: wasm.key.mode as Mode,
@@ -145,6 +155,7 @@ export function convertAnalysisResult(wasm: WasmAnalysisResult): AnalysisResult
       shortName: wasm.key.shortName,
     },
     timeSignature: wasm.timeSignature,
+    timeSignatureCandidates: wasm.timeSignatureCandidates,
     beatTimes,
     beats: wasm.beats,
     chords: wasm.chords.map((c) => ({

package/src/audio.ts

@@ -239,9 +239,14 @@ export class Audio {
     }
   }
 
-  /** The raw audio samples. */
+  /**
+   * A copy of the raw audio samples. Mirrors Node's `getData()` contract: the
+   * returned array is independent of the Audio's internal buffer, so mutating
+   * it (or transferring it to a Worker) does not affect subsequent facade
+   * calls, which all read the internal snapshot directly.
+   */
   get data(): Float32Array {
-    return this._samples;
+    return this._samples.slice();
   }
 
   /** Number of samples. */

package/src/clip_page_streamer.ts

@@ -11,7 +11,17 @@ import type { ClipPageProvider, ClipPageRequest, RealtimeEngine } from './realti
  */
 export interface ClipPageStreamerEngine {
   /** Drain one pending audio-thread page-miss request, or `null` when empty. */
-  popClipPageRequest(): ClipPageRequest | null;
+  popClipPageRequest(): ClipPageStreamerRequest | null;
+}
+
+/**
+ * A page miss reported by either a direct engine (`sample`) or the worklet
+ * bridge (`pageIndex`). Exactly one position form is required.
+ */
+export interface ClipPageStreamerRequest {
+  clipId: number;
+  sample?: number;
+  pageIndex?: number;
 }
 
 /** A paged clip the streamer keeps fed from its backing store. */
@@ -153,7 +163,13 @@ export class ClipPageStreamer {
       if (!state) {
         continue;
       }
-      const page = Math.floor(request.sample / state.source.pageFrames);
+      const page =
+        request.pageIndex !== undefined
+          ? request.pageIndex
+          : Math.floor((request.sample ?? Number.NaN) / state.source.pageFrames);
+      if (!Number.isInteger(page) || page < 0 || page > state.lastPage) {
+        continue;
+      }
       frontiers.set(request.clipId, page);
     }
 
@@ -197,7 +213,7 @@ export class ClipPageStreamer {
     // the bound by transiently holding old pages alongside new ones.
     for (const page of state.resident.keys()) {
       if (page < low || page > high) {
-        state.source.binding.provider.clear(page);
+        this.clearPage(state, page);
         state.resident.delete(page);
       }
     }
@@ -217,7 +233,7 @@ export class ClipPageStreamer {
             if (state.generation !== generation) {
               // The fetch crossed a seek/reset boundary. supplyPage may have
               // installed it after resetState's clear pass, so clear it again.
-              state.source.binding.provider.clear(pageIndex);
+              this.clearPage(state, pageIndex);
             } else if (!ok && state.resident.get(pageIndex) === generation) {
               state.resident.delete(pageIndex);
             }
@@ -239,10 +255,20 @@ export class ClipPageStreamer {
     state.generation += 1;
     state.lastFrontier = null;
     for (const page of state.resident.keys()) {
-      state.source.binding.provider.clear(page);
+      this.clearPage(state, page);
     }
     state.resident.clear();
   }
+
+  private clearPage(state: SourceState, pageIndex: number): void {
+    // `clearPage` mirrors eviction into the AudioWorklet. Keep the older
+    // provider-only form working for direct-engine callers and test doubles.
+    if (state.source.binding.clearPage) {
+      state.source.binding.clearPage(pageIndex);
+    } else {
+      state.source.binding.provider.clear(pageIndex);
+    }
+  }
 }
 
 export interface OpfsClipStreamOptions extends OpfsClipPageProviderOptions {
@@ -257,25 +283,53 @@ export interface OpfsClipStreamOptions extends OpfsClipPageProviderOptions {
 
 export interface OpfsClipStream {
   binding: OpfsClipPageProviderBinding;
-  /** Pass to `setClips({ pageProvider })` to schedule the streaming clip. */
+  /** Pass as `addClip`'s buffer argument to schedule the streaming clip. */
   provider: ClipPageProvider;
 }
 
+/** Structural seam implemented by the AudioWorklet-backed `SonareEngine`. */
+export interface WorkletOpfsClipStreamHost {
+  attachOpfsClipStream(options: OpfsClipStreamOptions): Promise<OpfsClipStream>;
+}
+
 /**
  * One-call wiring of an OPFS-backed streaming clip: creates the page provider,
  * primes the leading pages, and registers it with `streamer` so later misses are
  * serviced within the bounded window. Returns the binding (for `close`) and the
- * provider to schedule via `setClips({ pageProvider })`.
+ * provider to schedule via `addClip(trackId, provider, startPpq, { id: clipId })`.
  *
  * @param streamer Shared streamer pumped on the control thread.
  * @param engine Engine the provider is created on (the same one `streamer` drives).
  * @param options Provider options plus `clipId` and optional `primePages`.
  */
-export async function attachOpfsClipStream(
+export function attachOpfsClipStream(
   streamer: ClipPageStreamer,
   engine: RealtimeEngine,
   options: OpfsClipStreamOptions,
+): Promise<OpfsClipStream>;
+/**
+ * Worklet overload: delegates to `SonareEngine.attachOpfsClipStream`, which
+ * creates the remote provider and drives this same sliding-window policy from
+ * worklet page-miss messages.
+ */
+export function attachOpfsClipStream(
+  engine: WorkletOpfsClipStreamHost,
+  options: OpfsClipStreamOptions,
+): Promise<OpfsClipStream>;
+export async function attachOpfsClipStream(
+  streamerOrEngine: ClipPageStreamer | WorkletOpfsClipStreamHost,
+  engineOrOptions: RealtimeEngine | OpfsClipStreamOptions,
+  maybeOptions?: OpfsClipStreamOptions,
 ): Promise<OpfsClipStream> {
+  if (!(streamerOrEngine instanceof ClipPageStreamer)) {
+    return streamerOrEngine.attachOpfsClipStream(engineOrOptions as OpfsClipStreamOptions);
+  }
+  const streamer = streamerOrEngine;
+  const engine = engineOrOptions as RealtimeEngine;
+  const options = maybeOptions;
+  if (!options) {
+    throw new Error('attachOpfsClipStream requires options.');
+  }
   const { clipId, primePages = 1, ...providerOptions } = options;
   const binding = createOpfsClipPageProvider(engine, providerOptions);
   const lastPage = Math.ceil(providerOptions.numSamples / providerOptions.pageFrames) - 1;

package/src/codes.ts

@@ -1,68 +1,96 @@
-import type { AutomationCurve, MeterTap, PanLaw, PanMode, SendTiming } from './public_types';
+import type { AutomationCurve, MeterTap, PanLawInput, PanMode, SendTiming } from './public_types';
 
-export function automationCurveCode(curve: AutomationCurve): number {
-  switch (curve) {
-    case 'linear':
-      return 0;
-    case 'exponential':
-      return 1;
-    case 'hold':
-      return 2;
-    case 's-curve':
-      return 3;
-    default:
-      throw new Error(`Invalid automation curve: ${curve}`);
+/** Resolve a numeric ordinal in an inclusive range without coercion. */
+export function resolveOrdinalInRange(
+  value: unknown,
+  min: number,
+  max: number,
+  enumName: string,
+): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
   }
+  return value;
 }
 
-export function panLawCode(panLaw: PanLaw | number): number {
-  if (typeof panLaw === 'number') {
-    return panLaw;
+/** Resolve a public enum spelling or ordinal without permitting unknown values. */
+export function resolveEnumOrdinal(
+  value: unknown,
+  values: Readonly<Record<string, number>>,
+  enumName: string,
+): number {
+  if (typeof value === 'number') {
+    const ordinals = Object.values(values);
+    const ordinal = resolveOrdinalInRange(
+      value,
+      Math.min(...ordinals),
+      Math.max(...ordinals),
+      enumName,
+    );
+    if (!ordinals.includes(ordinal)) {
+      throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
+    }
+    return ordinal;
   }
-  switch (panLaw) {
-    case 'const3dB':
-      return 0;
-    case 'const4.5dB':
-      return 1;
-    case 'const6dB':
-      return 2;
-    case 'linear0dB':
-      return 3;
-    default:
-      throw new Error(`Invalid pan law: ${panLaw}`);
+  if (typeof value === 'string') {
+    const ordinal = values[value];
+    if (ordinal !== undefined) {
+      return ordinal;
+    }
   }
+  throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
+}
+
+const AUTOMATION_CURVE_VALUES = {
+  linear: 0,
+  exponential: 1,
+  hold: 2,
+  's-curve': 3,
+} as const;
+const PAN_LAW_VALUES: Readonly<Record<string, number>> = {
+  const3db: 0,
+  'const-3db': 0,
+  '-3db': 0,
+  'const4.5db': 1,
+  'const-4.5db': 1,
+  '-4.5db': 1,
+  const6db: 2,
+  'const-6db': 2,
+  '-6db': 2,
+  linear0db: 3,
+  'linear-0db': 3,
+  linear: 3,
+  '0db': 3,
+} as const;
+const PAN_MODE_VALUES = {
+  balance: 0,
+  pan: 1,
+  stereopan: 1,
+  'stereo-pan': 1,
+  dualpan: 2,
+  'dual-pan': 2,
+} as const;
+const METER_TAP_VALUES = { preFader: 0, postFader: 1 } as const;
+const SEND_TIMING_VALUES = { postFader: 0, preFader: 1 } as const;
+const TRACK_MONITOR_MODE_VALUES = { off: 0, pfl: 1, afl: 2 } as const;
+
+export function automationCurveCode(curve: AutomationCurve): number {
+  return resolveEnumOrdinal(curve, AUTOMATION_CURVE_VALUES, 'automation curve');
+}
+
+export function panLawCode(panLaw: PanLawInput): number {
+  const normalized = typeof panLaw === 'string' ? panLaw.toLowerCase().replace(/_/g, '-') : panLaw;
+  return resolveEnumOrdinal(normalized, PAN_LAW_VALUES, 'pan law');
 }
 
 export function panModeCode(panMode: PanMode | number): number {
-  if (typeof panMode === 'number') {
-    return panMode;
-  }
-  switch (panMode) {
-    case 'balance':
-      return 0;
-    case 'stereoPan':
-    case 'stereo-pan':
-      return 1;
-    case 'dualPan':
-    case 'dual-pan':
-      return 2;
-    default:
-      throw new Error(`Invalid pan mode: ${panMode}`);
-  }
+  const normalized =
+    typeof panMode === 'string' ? panMode.replace(/_/g, '-').toLowerCase() : panMode;
+  return resolveEnumOrdinal(normalized, PAN_MODE_VALUES, 'pan mode');
 }
 
 export function meterTapCode(tap: MeterTap | number): number {
-  if (typeof tap === 'number') {
-    return tap;
-  }
-  switch (tap) {
-    case 'preFader':
-      return 0;
-    case 'postFader':
-      return 1;
-    default:
-      throw new Error(`Invalid meter tap: ${tap}`);
-  }
+  return resolveEnumOrdinal(tap, METER_TAP_VALUES, 'meter tap');
 }
 
 export function sendTimingCode(timing: SendTiming | number): number {
@@ -70,15 +98,10 @@ export function sendTimingCode(timing: SendTiming | number): number {
   // post-fader), pre-fader is 1. A raw number is passed through as the C ABI int.
   // An unknown string is rejected rather than silently routed to post-fader,
   // matching the sibling enum-code helpers and Node's sendTimingValue.
-  if (typeof timing === 'number') {
-    return timing;
-  }
-  switch (timing) {
-    case 'postFader':
-      return 0;
-    case 'preFader':
-      return 1;
-    default:
-      throw new Error(`Invalid send timing: ${timing}`);
-  }
+  return resolveEnumOrdinal(timing, SEND_TIMING_VALUES, 'send timing');
+}
+
+/** Resolve a per-track PFL/AFL monitor mode to its C-ABI ordinal. */
+export function trackMonitorModeCode(mode: unknown): number {
+  return resolveEnumOrdinal(mode, TRACK_MONITOR_MODE_VALUES, 'track monitor mode');
 }

package/src/effects_mastering.ts

@@ -38,6 +38,7 @@ export type {
   MasteringProcessorCatalogEntry,
   MasteringProcessRequest,
   MasteringProcessStereoRequest,
+  MasteringRealtimeCost,
   MasteringSamplesParamsRequest,
   MasteringStereoAnalyzeRequest,
   MasteringStreamingPreviewRequest,