@libraz/libsonare 1.6.0 → 1.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "type": "module",
   "packageManager": "yarn@4.18.0",
   "description": "Audio analysis, mastering, mixing, and MIDI synthesis in WebAssembly",
@@ -38,7 +38,7 @@
     "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-baseline.json --artifact sonare.wasm=dist/sonare.wasm --artifact sonare-analysis.wasm=dist/sonare-analysis.wasm",
+    "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 && node scripts/copy-schemas.mjs",
@@ -47,7 +47,7 @@
     "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",
+    "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:worker": "node scripts/offline-worker-smoke.mjs",
     "test:browser:boundary": "node scripts/boundary-smoke.mjs",

package/src/_chain_config.ts

@@ -6,7 +6,12 @@ type ChainSection = { [key: string]: number | boolean | ChainSection | undefined
  * Flattens a nested {@link MasteringChainConfig} into the dot-notation
  * `{ "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.
+ * legacy leaf-name aliases, so this remains a structural flattening step.
+ *
+ * A key the caller already wrote in dot notation carries through untouched, so
+ * both spellings a {@link MasteringChainConfig} accepts reach the core as the
+ * same parameter — matching what the Python binding documents. An unknown key
+ * in either spelling is rejected by the core, not here.
  */
 export function flattenChainConfig(config: MasteringChainConfig): Record<string, number | boolean> {
   const out: Record<string, number | boolean> = {};

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 {

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/codes.ts

@@ -1,4 +1,17 @@
-import type { AutomationCurve, MeterTap, PanLaw, PanMode, SendTiming } from './public_types';
+import type { AutomationCurve, MeterTap, PanLawInput, PanMode, SendTiming } from './public_types';
+
+/** 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;
+}
 
 /** Resolve a public enum spelling or ordinal without permitting unknown values. */
 export function resolveEnumOrdinal(
@@ -7,10 +20,17 @@ export function resolveEnumOrdinal(
   enumName: string,
 ): number {
   if (typeof value === 'number') {
-    if (!Number.isSafeInteger(value) || !Object.values(values).includes(value)) {
+    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 value;
+    return ordinal;
   }
   if (typeof value === 'string') {
     const ordinal = values[value];
@@ -27,15 +47,24 @@ const AUTOMATION_CURVE_VALUES = {
   hold: 2,
   's-curve': 3,
 } as const;
-const PAN_LAW_VALUES = {
-  const3dB: 0,
-  'const4.5dB': 1,
-  const6dB: 2,
-  linear0dB: 3,
+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: 0,
+  pan: 1,
   stereopan: 1,
   'stereo-pan': 1,
   dualpan: 2,
@@ -43,13 +72,15 @@ const PAN_MODE_VALUES = {
 } 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: PanLaw | number): number {
-  return resolveEnumOrdinal(panLaw, PAN_LAW_VALUES, 'pan law');
+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 {
@@ -69,3 +100,8 @@ export function sendTimingCode(timing: SendTiming | number): number {
   // matching the sibling enum-code helpers and Node's sendTimingValue.
   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

@@ -41,12 +41,16 @@ export type {
   MasteringRealtimeCost,
   MasteringSamplesParamsRequest,
   MasteringStereoAnalyzeRequest,
+  MasteringStereoParamsRequest,
   MasteringStreamingPreviewRequest,
+  MasteringStreamingPreviewStereoRequest,
 } from './mastering_core';
 export {
   mastering,
   masteringAssistantSuggest,
+  masteringAssistantSuggestStereo,
   masteringAudioProfile,
+  masteringAudioProfileStereo,
   masteringInsertNames,
   masteringInsertParamInfo,
   masteringInsertParamNames,
@@ -61,6 +65,7 @@ export {
   masteringStereoAnalysisNames,
   masteringStereoAnalyze,
   masteringStreamingPreview,
+  masteringStreamingPreviewStereo,
 } from './mastering_core';
 export type {
   CompressorDetector,

package/src/effects_transform.ts

@@ -6,6 +6,7 @@ import type {
   PitchCorrectOptions,
   SpectralEditOptions,
   SpectralRegionOp,
+  VoicedFlags,
 } from './public_types';
 import type { ValidateOptions } from './validation';
 import { assertSampleRate, assertSamples } from './validation';
@@ -14,12 +15,77 @@ function requireModule() {
   return getSonareModule();
 }
 
+// The embind layer reads the companion voicing array as Float32Array. A flag is
+// a decision, not a magnitude: collapse to 1/0 on truthiness, which is the same
+// reduction the Node facade applies, so both surfaces agree on every accepted
+// input type.
+function toVoicedFloat32(voiced: VoicedFlags): Float32Array {
+  const out = new Float32Array(voiced.length);
+  for (let index = 0; index < voiced.length; index += 1) {
+    out[index] = voiced[index] ? 1 : 0;
+  }
+  return out;
+}
+
+function resolveEffectFftOptions(
+  fnName: string,
+  nFft: unknown,
+  hopLength: unknown,
+): { nFft: number; hopLength: number } {
+  const resolvedNFft = nFft === undefined ? 2048 : nFft;
+  const resolvedHopLength = hopLength === undefined ? 512 : hopLength;
+  if (typeof resolvedNFft !== 'number' || !Number.isInteger(resolvedNFft)) {
+    throw new TypeError(`${fnName}: nFft must be an integer`);
+  }
+  if (resolvedNFft < 2 || resolvedNFft > 2 ** 30) {
+    throw new RangeError(`${fnName}: nFft must be an even power of two >= 2`);
+  }
+  if ((resolvedNFft & (resolvedNFft - 1)) !== 0) {
+    throw new RangeError(`${fnName}: nFft must be an even power of two >= 2`);
+  }
+  if (typeof resolvedHopLength !== 'number' || !Number.isInteger(resolvedHopLength)) {
+    throw new TypeError(`${fnName}: hopLength must be an integer`);
+  }
+  if (resolvedHopLength <= 0 || resolvedHopLength > 2 ** 31 - 1) {
+    throw new RangeError(`${fnName}: hopLength must be a positive integer`);
+  }
+  return { nFft: resolvedNFft, hopLength: resolvedHopLength };
+}
+
+export type NormalizeMode = 'peak' | 'rms';
+
+function resolveNormalizeMode(value: unknown): NormalizeMode {
+  if (value === undefined) {
+    return 'peak';
+  }
+  if (typeof value !== 'string') {
+    throw new TypeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  if (value !== 'peak' && value !== 'rms') {
+    throw new RangeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  return value;
+}
+
+function resolveHardMask(value: unknown, fnName: string): boolean {
+  if (value === undefined) {
+    return false;
+  }
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`${fnName}: hardMask must be a boolean`);
+  }
+  return value;
+}
+
 /** Canonical request form for HPSS. */
 export interface HpssRequest {
   samples: Float32Array;
   sampleRate?: number;
   kernelHarmonic?: number;
   kernelPercussive?: number;
+  nFft?: number;
+  hopLength?: number;
+  hardMask?: boolean;
 }
 
 export interface HarmonicRequest extends ValidateOptions {
@@ -36,12 +102,16 @@ export interface TimeStretchRequest extends ValidateOptions {
   samples: Float32Array;
   sampleRate?: number;
   rate: number;
+  nFft?: number;
+  hopLength?: number;
 }
 
 export interface PitchShiftRequest extends ValidateOptions {
   samples: Float32Array;
   sampleRate?: number;
   semitones: number;
+  nFft?: number;
+  hopLength?: number;
 }
 
 export interface PitchCorrectToMidiRequest extends ValidateOptions {
@@ -57,7 +127,7 @@ export interface PitchCorrectToMidiTimevaryingRequest extends ValidateOptions {
   targetMidi: number;
   sampleRate?: number;
   hopLength?: number;
-  voiced?: Int32Array;
+  voiced?: VoicedFlags;
   voicedProb?: Float32Array;
 }
 
@@ -81,6 +151,7 @@ export interface NormalizeRequest extends ValidateOptions {
   samples: Float32Array;
   sampleRate?: number;
   targetDb?: number;
+  mode?: NormalizeMode;
 }
 
 export interface SpectralEditRequest extends SpectralEditOptions, ValidateOptions {
@@ -108,22 +179,33 @@ export function hpss(
   sampleRate?: number,
   kernelHarmonic?: number,
   kernelPercussive?: number,
+  nFft?: number,
+  hopLength?: number,
+  hardMask?: boolean,
 ): HpssResult;
 export function hpss(
   samples: Float32Array | HpssRequest,
   sampleRate = 22050,
   kernelHarmonic = 31,
   kernelPercussive = 31,
+  nFft?: number,
+  hopLength?: number,
+  hardMask?: boolean,
 ): HpssResult {
   const request =
     samples instanceof Float32Array
-      ? { samples, sampleRate, kernelHarmonic, kernelPercussive }
+      ? { samples, sampleRate, kernelHarmonic, kernelPercussive, nFft, hopLength, hardMask }
       : samples;
-  return requireModule().hpss(
+  const fftOptions = resolveEffectFftOptions('hpss', request.nFft, request.hopLength);
+  const resolvedHardMask = resolveHardMask(request.hardMask, 'hpss');
+  return requireModule().hpssEx(
     request.samples,
     request.sampleRate ?? 22050,
     request.kernelHarmonic ?? 31,
     request.kernelPercussive ?? 31,
+    fftOptions.nFft,
+    fftOptions.hopLength,
+    resolvedHardMask,
   );
 }
 
@@ -188,18 +270,56 @@ export function timeStretch(
   rate: number,
   options?: ValidateOptions,
 ): Float32Array;
+export function timeStretch(
+  samples: Float32Array,
+  sampleRate: number,
+  rate: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: ValidateOptions,
+): Float32Array;
 export function timeStretch(
   samples: Float32Array | TimeStretchRequest,
   sampleRate?: number,
   rate?: number,
+  nFftOrOptions?: number | ValidateOptions,
+  hopLength?: number,
   options: ValidateOptions = {},
 ): Float32Array {
+  if (
+    nFftOrOptions !== undefined &&
+    nFftOrOptions !== null &&
+    typeof nFftOrOptions !== 'number' &&
+    typeof nFftOrOptions !== 'object'
+  ) {
+    throw new TypeError('timeStretch: nFft must be an integer or options object');
+  }
+  if (nFftOrOptions === null) {
+    throw new TypeError('timeStretch: nFft must be an integer or options object');
+  }
+  const positionalOptions =
+    typeof nFftOrOptions === 'object' && nFftOrOptions !== null ? nFftOrOptions : options;
+  const positionalNFft = typeof nFftOrOptions === 'number' ? nFftOrOptions : undefined;
   const request: TimeStretchRequest =
     samples instanceof Float32Array
-      ? { samples, sampleRate, rate: rate as number, ...options }
+      ? {
+          samples,
+          sampleRate,
+          rate: rate as number,
+          nFft: positionalNFft,
+          hopLength,
+          ...positionalOptions,
+        }
       : samples;
   assertSamples('timeStretch', request.samples, request.validate !== false);
-  return requireModule().timeStretch(request.samples, request.sampleRate ?? 22050, request.rate);
+  const fftOptions = resolveEffectFftOptions('timeStretch', request.nFft, request.hopLength);
+  return requireModule().timeStretchEx(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.rate,
+    fftOptions.nFft,
+    fftOptions.hopLength,
+  );
 }
 
 /**
@@ -217,21 +337,55 @@ export function pitchShift(
   semitones: number,
   options?: ValidateOptions,
 ): Float32Array;
+export function pitchShift(
+  samples: Float32Array,
+  sampleRate: number,
+  semitones: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: ValidateOptions,
+): Float32Array;
 export function pitchShift(
   samples: Float32Array | PitchShiftRequest,
   sampleRate?: number,
   semitones?: number,
+  nFftOrOptions?: number | ValidateOptions,
+  hopLength?: number,
   options: ValidateOptions = {},
 ): Float32Array {
+  if (
+    nFftOrOptions !== undefined &&
+    nFftOrOptions !== null &&
+    typeof nFftOrOptions !== 'number' &&
+    typeof nFftOrOptions !== 'object'
+  ) {
+    throw new TypeError('pitchShift: nFft must be an integer or options object');
+  }
+  if (nFftOrOptions === null) {
+    throw new TypeError('pitchShift: nFft must be an integer or options object');
+  }
+  const positionalOptions =
+    typeof nFftOrOptions === 'object' && nFftOrOptions !== null ? nFftOrOptions : options;
+  const positionalNFft = typeof nFftOrOptions === 'number' ? nFftOrOptions : undefined;
   const request: PitchShiftRequest =
     samples instanceof Float32Array
-      ? { samples, sampleRate, semitones: semitones as number, ...options }
+      ? {
+          samples,
+          sampleRate,
+          semitones: semitones as number,
+          nFft: positionalNFft,
+          hopLength,
+          ...positionalOptions,
+        }
       : samples;
   assertSamples('pitchShift', request.samples, request.validate !== false);
-  return requireModule().pitchShift(
+  const fftOptions = resolveEffectFftOptions('pitchShift', request.nFft, request.hopLength);
+  return requireModule().pitchShiftEx(
     request.samples,
     request.sampleRate ?? 22050,
     request.semitones,
+    fftOptions.nFft,
+    fftOptions.hopLength,
   );
 }
 
@@ -282,16 +436,18 @@ export function pitchCorrectToMidi(
  * Unlike {@link pitchCorrectToMidi} (a single constant transpose), this follows
  * the caller-supplied per-frame `f0Hz` contour and retunes every voiced frame
  * toward `targetMidi`, so vibrato/drift in the source is tracked rather than
- * flattened. `voiced` (non-zero = voiced) and `voicedProb` ([0,1]) are optional;
+ * flattened. `voiced` (truthy = voiced) and `voicedProb` ([0,1]) are optional;
  * omitting them treats every frame as voiced. An `f0Hz` NaN is accepted only
- * when the corresponding `voiced` entry is zero, matching pYIN output.
+ * when the corresponding `voiced` entry is falsy, matching pYIN output. The
+ * `voicedFlag` / `voicedProb` arrays of a {@link PitchResult} can be passed
+ * through directly.
  *
  * @param samples - Audio samples (mono, float32)
  * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
  * @param targetMidi - Desired MIDI note number
  * @param sampleRate - Sample rate in Hz
  * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
- * @param voiced - Optional per-frame voiced flags (non-zero = voiced)
+ * @param voiced - Optional per-frame voiced flags (truthy = voiced)
  * @param voicedProb - Optional per-frame voicing probability in [0, 1]
  * @returns Pitch-corrected audio
  */
@@ -304,7 +460,7 @@ export function pitchCorrectToMidiTimevarying(
   targetMidi: number,
   sampleRate?: number,
   hopLength?: number,
-  voiced?: Int32Array,
+  voiced?: VoicedFlags,
   voicedProb?: Float32Array,
   options?: ValidateOptions,
 ): Float32Array;
@@ -314,7 +470,7 @@ export function pitchCorrectToMidiTimevarying(
   targetMidi?: number,
   sampleRate = 22050,
   hopLength = 512,
-  voiced?: Int32Array,
+  voiced?: VoicedFlags,
   voicedProb?: Float32Array,
   options: ValidateOptions = {},
 ): Float32Array {
@@ -338,9 +494,7 @@ export function pitchCorrectToMidiTimevarying(
   if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
     throw new RangeError('pitchCorrectToMidiTimevarying: voicedProb length must match f0Hz length');
   }
-  // The embind layer reads the companion arrays as Float32Array (voiced uses
-  // 0.0/1.0); convert here so a single native conversion path suffices.
-  const voicedF32 = request.voiced ? Float32Array.from(request.voiced) : undefined;
+  const voicedF32 = request.voiced ? toVoicedFloat32(request.voiced) : undefined;
   return requireModule().pitchCorrectToMidiTimevarying(
     request.samples,
     request.sampleRate ?? 22050,
@@ -395,11 +549,9 @@ export function pitchCorrectTimevarying(
   if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
     throw new RangeError('pitchCorrectTimevarying: voicedProb length must match f0Hz length');
   }
-  // The embind layer reads the companion arrays as Float32Array (voiced uses
-  // 0.0/1.0); convert here so a single native conversion path suffices.
   const nativeOptions = {
     ...request,
-    voiced: request.voiced ? Float32Array.from(request.voiced) : undefined,
+    voiced: request.voiced ? toVoicedFloat32(request.voiced) : undefined,
   };
   return requireModule().pitchCorrectTimevarying(
     request.samples,
@@ -466,11 +618,13 @@ export function noteMove(
 }
 
 /**
- * Normalize audio to target peak level.
+ * Normalize audio to a target peak or RMS level.
  *
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz (default: 22050)
- * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale)
+ * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale).
+ *   For `mode: 'peak'`, this is the peak target; for `mode: 'rms'`, this is the RMS target.
+ * @param mode - Normalization mode: `'peak'` (default) or `'rms'`.
  * @returns Normalized audio
  */
 export function normalize(request: NormalizeRequest): Float32Array;
@@ -480,19 +634,45 @@ export function normalize(
   targetDb?: number,
   options?: ValidateOptions,
 ): Float32Array;
+export function normalize(
+  samples: Float32Array,
+  sampleRate: number,
+  targetDb?: number,
+  mode?: NormalizeMode,
+  options?: ValidateOptions,
+): Float32Array;
 export function normalize(
   samples: Float32Array | NormalizeRequest,
   sampleRate?: number,
   targetDb = 0.0,
+  modeOrOptions: NormalizeMode | ValidateOptions = 'peak',
   options: ValidateOptions = {},
 ): Float32Array {
+  if (
+    modeOrOptions !== undefined &&
+    modeOrOptions !== null &&
+    typeof modeOrOptions !== 'string' &&
+    typeof modeOrOptions !== 'object'
+  ) {
+    throw new TypeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  if (modeOrOptions === null) {
+    throw new TypeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  const positionalOptions =
+    typeof modeOrOptions === 'object' && modeOrOptions !== null ? modeOrOptions : options;
+  const positionalMode = typeof modeOrOptions === 'string' ? modeOrOptions : undefined;
   const request: NormalizeRequest =
-    samples instanceof Float32Array ? { samples, sampleRate, targetDb, ...options } : samples;
+    samples instanceof Float32Array
+      ? { samples, sampleRate, targetDb, mode: positionalMode, ...positionalOptions }
+      : samples;
   assertSamples('normalize', request.samples, request.validate !== false);
-  return requireModule().normalize(
+  const mode = resolveNormalizeMode(request.mode);
+  return requireModule().normalizeEx(
     request.samples,
     request.sampleRate ?? 22050,
     request.targetDb ?? 0.0,
+    mode,
   );
 }