@libraz/libsonare 1.5.2 → 1.5.4

package/src/metering.ts

@@ -2,6 +2,25 @@ import { getSonareModule } from './module_state';
 import type { ValidateOptions } from './validation';
 import { assertSamples } from './validation';
 
+/**
+ * Validates a true-peak oversample factor: `0` (meaning "use the default 4") or
+ * a power of two in `[1, 16]`. The native layer applies the same `0 -> 4`
+ * normalization (see `metering::true_peak_db`), so the raw factor can be passed
+ * through unchanged after this check. Kept module-local (not exported) so it does
+ * not surface as a WASM-only symbol with no C-API counterpart.
+ */
+function assertOversampleFactor(fnName: string, factor: number): void {
+  const normalized = factor === 0 ? 4 : factor;
+  if (
+    !Number.isInteger(normalized) ||
+    normalized < 1 ||
+    normalized > 16 ||
+    (normalized & (normalized - 1)) !== 0
+  ) {
+    throw new RangeError(`${fnName}: oversampleFactor must be 0 or a power of two from 1 to 16`);
+  }
+}
+
 // ============================================================================
 // Metering — basic / true-peak / clipping / dynamic range
 // ============================================================================
@@ -50,64 +69,122 @@ export interface MeteringDynamicRangeOptions extends ValidateOptions {
   highPercentile?: number;
 }
 
+/** Canonical request form for single-channel meter readings. */
+export interface MeteringSamplesRequest extends ValidateOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+}
+
+/** Canonical request form for true-peak analysis. */
+export interface MeteringTruePeakRequest extends MeteringSamplesRequest {
+  oversampleFactor?: number;
+}
+
+/** Canonical request form for clipping analysis. */
+export interface MeteringDetectClippingRequest extends MeteringDetectClippingOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+}
+
+/** Canonical request form for dynamic-range analysis. */
+export interface MeteringDynamicRangeRequest extends MeteringDynamicRangeOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+}
+
 function requireModule() {
   return getSonareModule();
 }
 
+export function meteringPeakDb(request: MeteringSamplesRequest): number;
 export function meteringPeakDb(
   samples: Float32Array,
+  sampleRate?: number,
+  options?: ValidateOptions,
+): number;
+export function meteringPeakDb(
+  samples: Float32Array | MeteringSamplesRequest,
   sampleRate = 22050,
   options: ValidateOptions = {},
 ): number {
-  assertSamples('meteringPeakDb', samples, options.validate !== false);
-  return requireModule().meteringPeakDb(samples, sampleRate);
+  const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
+  assertSamples('meteringPeakDb', request.samples, request.validate !== false);
+  return requireModule().meteringPeakDb(request.samples, request.sampleRate ?? 22050);
 }
 
+export function meteringRmsDb(request: MeteringSamplesRequest): number;
 export function meteringRmsDb(
   samples: Float32Array,
+  sampleRate?: number,
+  options?: ValidateOptions,
+): number;
+export function meteringRmsDb(
+  samples: Float32Array | MeteringSamplesRequest,
   sampleRate = 22050,
   options: ValidateOptions = {},
 ): number {
-  assertSamples('meteringRmsDb', samples, options.validate !== false);
-  return requireModule().meteringRmsDb(samples, sampleRate);
+  const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
+  assertSamples('meteringRmsDb', request.samples, request.validate !== false);
+  return requireModule().meteringRmsDb(request.samples, request.sampleRate ?? 22050);
 }
 
+export function meteringCrestFactorDb(request: MeteringSamplesRequest): number;
 export function meteringCrestFactorDb(
   samples: Float32Array,
+  sampleRate?: number,
+  options?: ValidateOptions,
+): number;
+export function meteringCrestFactorDb(
+  samples: Float32Array | MeteringSamplesRequest,
   sampleRate = 22050,
   options: ValidateOptions = {},
 ): number {
-  assertSamples('meteringCrestFactorDb', samples, options.validate !== false);
-  return requireModule().meteringCrestFactorDb(samples, sampleRate);
+  const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
+  assertSamples('meteringCrestFactorDb', request.samples, request.validate !== false);
+  return requireModule().meteringCrestFactorDb(request.samples, request.sampleRate ?? 22050);
 }
 
+export function meteringDcOffset(request: MeteringSamplesRequest): number;
 export function meteringDcOffset(
   samples: Float32Array,
+  sampleRate?: number,
+  options?: ValidateOptions,
+): number;
+export function meteringDcOffset(
+  samples: Float32Array | MeteringSamplesRequest,
   sampleRate = 22050,
   options: ValidateOptions = {},
 ): number {
-  assertSamples('meteringDcOffset', samples, options.validate !== false);
-  return requireModule().meteringDcOffset(samples, sampleRate);
+  const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
+  assertSamples('meteringDcOffset', request.samples, request.validate !== false);
+  return requireModule().meteringDcOffset(request.samples, request.sampleRate ?? 22050);
 }
 
 /**
  * Inter-sample (true) peak in dBFS. `oversampleFactor` must be a power of two
  * in [1, 16]; pass 0 to use the library default (4).
  */
+export function meteringTruePeakDb(request: MeteringTruePeakRequest): number;
 export function meteringTruePeakDb(
   samples: Float32Array,
+  sampleRate?: number,
+  oversampleFactor?: number,
+  options?: ValidateOptions,
+): number;
+export function meteringTruePeakDb(
+  samples: Float32Array | MeteringTruePeakRequest,
   sampleRate = 22050,
   oversampleFactor = 4,
   options: ValidateOptions = {},
 ): number {
-  assertSamples('meteringTruePeakDb', samples, options.validate !== false);
-  const factor = oversampleFactor === 0 ? 4 : oversampleFactor;
-  if (factor < 1 || factor > 16 || (factor & (factor - 1)) !== 0) {
-    throw new RangeError(
-      'meteringTruePeakDb: oversampleFactor must be 0 or a power of two from 1 to 16',
-    );
-  }
-  return requireModule().meteringTruePeakDb(samples, sampleRate, oversampleFactor);
+  const request =
+    samples instanceof Float32Array
+      ? { samples, sampleRate, oversampleFactor, ...options }
+      : samples;
+  assertSamples('meteringTruePeakDb', request.samples, request.validate !== false);
+  const factor = request.oversampleFactor ?? 4;
+  assertOversampleFactor('meteringTruePeakDb', factor);
+  return requireModule().meteringTruePeakDb(request.samples, request.sampleRate ?? 22050, factor);
 }
 
 /**
@@ -116,17 +193,24 @@ export function meteringTruePeakDb(
  * @param threshold Linear absolute threshold (default 0.999).
  * @param minRegionSamples Minimum run length to report (default 1).
  */
+export function meteringDetectClipping(request: MeteringDetectClippingRequest): ClippingReport;
 export function meteringDetectClipping(
   samples: Float32Array,
+  sampleRate?: number,
+  options?: MeteringDetectClippingOptions,
+): ClippingReport;
+export function meteringDetectClipping(
+  samples: Float32Array | MeteringDetectClippingRequest,
   sampleRate = 22050,
   options: MeteringDetectClippingOptions = {},
 ): ClippingReport {
-  assertSamples('meteringDetectClipping', samples, options.validate !== false);
+  const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
+  assertSamples('meteringDetectClipping', request.samples, request.validate !== false);
   return requireModule().meteringDetectClipping(
-    samples,
-    sampleRate,
-    options.threshold ?? 0.999,
-    options.minRegionSamples ?? 1,
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.threshold ?? 0.999,
+    request.minRegionSamples ?? 1,
   );
 }
 
@@ -136,19 +220,26 @@ export function meteringDetectClipping(
  * "use the library default" (low=0.10, high=0.95) because 0 is a literal 0th
  * percentile; omitted percentiles therefore default to -1.
  */
+export function meteringDynamicRange(request: MeteringDynamicRangeRequest): DynamicRangeReport;
 export function meteringDynamicRange(
   samples: Float32Array,
+  sampleRate?: number,
+  options?: MeteringDynamicRangeOptions,
+): DynamicRangeReport;
+export function meteringDynamicRange(
+  samples: Float32Array | MeteringDynamicRangeRequest,
   sampleRate = 22050,
   options: MeteringDynamicRangeOptions = {},
 ): DynamicRangeReport {
-  assertSamples('meteringDynamicRange', samples, options.validate !== false);
+  const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
+  assertSamples('meteringDynamicRange', request.samples, request.validate !== false);
   return requireModule().meteringDynamicRange(
-    samples,
-    sampleRate,
-    options.windowSec ?? 0,
-    options.hopSec ?? 0,
-    options.lowPercentile ?? -1,
-    options.highPercentile ?? -1,
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.windowSec ?? 0,
+    request.hopSec ?? 0,
+    request.lowPercentile ?? -1,
+    request.highPercentile ?? -1,
   );
 }
 
@@ -209,6 +300,51 @@ export interface WaveformPeakPyramidOptions extends ValidateOptions {
   samplesPerBucketLevels?: number[];
 }
 
+/** Canonical request form for stereo meter readings. */
+export interface MeteringStereoRequest extends ValidateOptions {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+}
+
+/** Canonical request form for display-decimated stereo scopes. */
+export interface MeteringStereoDecimatedRequest extends MeteringStereoRequest {
+  maxPoints?: number;
+}
+
+/** Options for the scope functions (mirrors the Node `ScopeOptions`). */
+export interface ScopeOptions extends ValidateOptions {
+  /**
+   * Upper bound on the returned point count. Omit / `0` (or a value `>= length`)
+   * yields one point per input sample; otherwise the point cloud is
+   * deterministically decimated to at most `maxPoints` points for display.
+   */
+  maxPoints?: number;
+}
+
+/** Canonical request form for whole-signal spectrum analysis. */
+export interface MeteringSpectrumRequest extends SpectrumOptions, ValidateOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+}
+
+/** Canonical request form for a single spectrum frame. */
+export interface MeteringSpectrumFrameRequest extends MeteringSpectrumRequest {
+  frameOffset?: number;
+}
+
+/** Canonical request form for waveform bucket generation. */
+export interface WaveformPeaksRequest extends WaveformPeaksOptions {
+  samples: Float32Array;
+  channels: number;
+}
+
+/** Canonical request form for multi-resolution waveform bucket generation. */
+export interface WaveformPeakPyramidRequest extends WaveformPeakPyramidOptions {
+  samples: Float32Array;
+  channels: number;
+}
+
 /** Per-channel min/max waveform buckets. Arrays are channel-major. */
 export interface WaveformPeaksReport {
   min: Float32Array;
@@ -219,97 +355,209 @@ export interface WaveformPeaksReport {
 }
 
 /** Pearson correlation in [-1, 1] between two equal-length channels. */
+export function meteringStereoCorrelation(request: MeteringStereoRequest): number;
 export function meteringStereoCorrelation(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  options?: ValidateOptions,
+): number;
+export function meteringStereoCorrelation(
+  left: Float32Array | MeteringStereoRequest,
+  right?: Float32Array,
   sampleRate = 22050,
   options: ValidateOptions = {},
 ): number {
-  const validate = options.validate !== false;
-  assertSamples('meteringStereoCorrelation', left, validate, 'left');
-  assertSamples('meteringStereoCorrelation', right, validate, 'right');
-  return requireModule().meteringStereoCorrelation(left, right, sampleRate);
+  const request =
+    left instanceof Float32Array
+      ? { left, right: right as Float32Array, sampleRate, ...options }
+      : left;
+  const validate = request.validate !== false;
+  assertSamples('meteringStereoCorrelation', request.left, validate, 'left');
+  assertSamples('meteringStereoCorrelation', request.right, validate, 'right');
+  return requireModule().meteringStereoCorrelation(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+  );
 }
 
 /**
- * Side / mid energy ratio, clamped to `[0, 2]`: 0 = pure mono, ~1 = wide
- * stereo, 2 = fully decorrelated / out-of-phase.
+ * Side / mid energy ratio in `[0, +Infinity)`: 0 = pure mono, ~1 = wide stereo,
+ * larger = increasingly decorrelated / out-of-phase. The value is unbounded and
+ * returns `Infinity` when the mid channel is silent (a mono-collapsed / fully
+ * out-of-phase signal).
  */
+export function meteringStereoWidth(request: MeteringStereoRequest): number;
 export function meteringStereoWidth(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  options?: ValidateOptions,
+): number;
+export function meteringStereoWidth(
+  left: Float32Array | MeteringStereoRequest,
+  right?: Float32Array,
   sampleRate = 22050,
   options: ValidateOptions = {},
 ): number {
-  const validate = options.validate !== false;
-  assertSamples('meteringStereoWidth', left, validate, 'left');
-  assertSamples('meteringStereoWidth', right, validate, 'right');
-  return requireModule().meteringStereoWidth(left, right, sampleRate);
+  const request =
+    left instanceof Float32Array
+      ? { left, right: right as Float32Array, sampleRate, ...options }
+      : left;
+  const validate = request.validate !== false;
+  assertSamples('meteringStereoWidth', request.left, validate, 'left');
+  assertSamples('meteringStereoWidth', request.right, validate, 'right');
+  return requireModule().meteringStereoWidth(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+  );
 }
 
-/** Per-sample mid/side point series (one entry per input frame). */
+/**
+ * Mid/side vectorscope point series. By default emits one point per input
+ * sample; pass `maxPoints` to get a display-sized decimated point set (matching
+ * the Node `meteringVectorscope` shape).
+ */
+export function meteringVectorscope(request: MeteringStereoDecimatedRequest): VectorscopeReport;
 export function meteringVectorscope(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  options?: ScopeOptions,
+): VectorscopeReport;
+export function meteringVectorscope(
+  left: Float32Array | MeteringStereoDecimatedRequest,
+  right?: Float32Array,
   sampleRate = 22050,
-  options: ValidateOptions = {},
+  options: ScopeOptions = {},
 ): VectorscopeReport {
-  const validate = options.validate !== false;
-  assertSamples('meteringVectorscope', left, validate, 'left');
-  assertSamples('meteringVectorscope', right, validate, 'right');
-  return requireModule().meteringVectorscope(left, right, sampleRate);
+  const request =
+    left instanceof Float32Array
+      ? { left, right: right as Float32Array, sampleRate, ...options }
+      : left;
+  const validate = request.validate !== false;
+  assertSamples('meteringVectorscope', request.left, validate, 'left');
+  assertSamples('meteringVectorscope', request.right, validate, 'right');
+  return requireModule().meteringVectorscopeDecimated(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.maxPoints ?? 0,
+  );
 }
 
 /**
- * Display-sized mid/side vectorscope. Like {@link meteringVectorscope} but the
- * point series is deterministically decimated to at most `maxPoints` points
- * (`0`, or a value `>= length`, yields one point per input sample). Mirrors the
- * Node/Python decimated vectorscope.
+ * Display-sized mid/side vectorscope.
+ *
+ * @deprecated Pass `maxPoints` to {@link meteringVectorscope} instead; it now
+ * folds `maxPoints` into the request, matching the Node surface. This alias is
+ * kept for backward compatibility and simply delegates.
  */
+export function meteringVectorscopeDecimated(
+  request: MeteringStereoDecimatedRequest,
+): VectorscopeReport;
 export function meteringVectorscopeDecimated(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  maxPoints?: number,
+  options?: ValidateOptions,
+): VectorscopeReport;
+export function meteringVectorscopeDecimated(
+  left: Float32Array | MeteringStereoDecimatedRequest,
+  right?: Float32Array,
   sampleRate = 22050,
   maxPoints = 0,
   options: ValidateOptions = {},
 ): VectorscopeReport {
-  const validate = options.validate !== false;
-  assertSamples('meteringVectorscopeDecimated', left, validate, 'left');
-  assertSamples('meteringVectorscopeDecimated', right, validate, 'right');
-  return requireModule().meteringVectorscopeDecimated(left, right, sampleRate, maxPoints);
+  const request =
+    left instanceof Float32Array
+      ? { left, right: right as Float32Array, sampleRate, maxPoints, ...options }
+      : left;
+  const validate = request.validate !== false;
+  assertSamples('meteringVectorscopeDecimated', request.left, validate, 'left');
+  assertSamples('meteringVectorscopeDecimated', request.right, validate, 'right');
+  return requireModule().meteringVectorscopeDecimated(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.maxPoints ?? 0,
+  );
 }
 
-/** Phase-scope point series plus summary stats. */
+/**
+ * Phase-scope point series plus summary stats. By default emits one point per
+ * input sample; pass `maxPoints` to decimate the point cloud for display
+ * (matching the Node `meteringPhaseScope` shape). The summary stats are always
+ * computed over the full-resolution signal.
+ */
+export function meteringPhaseScope(request: MeteringStereoDecimatedRequest): PhaseScopeReport;
 export function meteringPhaseScope(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  options?: ScopeOptions,
+): PhaseScopeReport;
+export function meteringPhaseScope(
+  left: Float32Array | MeteringStereoDecimatedRequest,
+  right?: Float32Array,
   sampleRate = 22050,
-  options: ValidateOptions = {},
+  options: ScopeOptions = {},
 ): PhaseScopeReport {
-  const validate = options.validate !== false;
-  assertSamples('meteringPhaseScope', left, validate, 'left');
-  assertSamples('meteringPhaseScope', right, validate, 'right');
-  return requireModule().meteringPhaseScope(left, right, sampleRate);
+  const request =
+    left instanceof Float32Array
+      ? { left, right: right as Float32Array, sampleRate, ...options }
+      : left;
+  const validate = request.validate !== false;
+  assertSamples('meteringPhaseScope', request.left, validate, 'left');
+  assertSamples('meteringPhaseScope', request.right, validate, 'right');
+  return requireModule().meteringPhaseScopeDecimated(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.maxPoints ?? 0,
+  );
 }
 
 /**
- * Display-sized phase scope. Like {@link meteringPhaseScope} but the point
- * series is deterministically decimated to at most `maxPoints` points (`0`, or
- * a value `>= length`, yields one point per input sample). The summary stats are
- * always computed over the full-resolution signal. Mirrors the Node/Python
- * decimated phase scope.
+ * Display-sized phase scope.
+ *
+ * @deprecated Pass `maxPoints` to {@link meteringPhaseScope} instead; it now
+ * folds `maxPoints` into the request, matching the Node surface. This alias is
+ * kept for backward compatibility and simply delegates.
  */
+export function meteringPhaseScopeDecimated(
+  request: MeteringStereoDecimatedRequest,
+): PhaseScopeReport;
 export function meteringPhaseScopeDecimated(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  maxPoints?: number,
+  options?: ValidateOptions,
+): PhaseScopeReport;
+export function meteringPhaseScopeDecimated(
+  left: Float32Array | MeteringStereoDecimatedRequest,
+  right?: Float32Array,
   sampleRate = 22050,
   maxPoints = 0,
   options: ValidateOptions = {},
 ): PhaseScopeReport {
-  const validate = options.validate !== false;
-  assertSamples('meteringPhaseScopeDecimated', left, validate, 'left');
-  assertSamples('meteringPhaseScopeDecimated', right, validate, 'right');
-  return requireModule().meteringPhaseScopeDecimated(left, right, sampleRate, maxPoints);
+  const request =
+    left instanceof Float32Array
+      ? { left, right: right as Float32Array, sampleRate, maxPoints, ...options }
+      : left;
+  const validate = request.validate !== false;
+  assertSamples('meteringPhaseScopeDecimated', request.left, validate, 'left');
+  assertSamples('meteringPhaseScopeDecimated', request.right, validate, 'right');
+  return requireModule().meteringPhaseScopeDecimated(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.maxPoints ?? 0,
+  );
 }
 
 /**
@@ -318,14 +566,20 @@ export function meteringPhaseScopeDecimated(
  * are averaged). For a true single-frame snapshot, use
  * {@link meteringSpectrumFrame}.
  */
+export function meteringSpectrum(request: MeteringSpectrumRequest): SpectrumReport;
 export function meteringSpectrum(
   samples: Float32Array,
-  sampleRate = 22050,
+  sampleRate?: number,
   options?: SpectrumOptions & ValidateOptions,
+): SpectrumReport;
+export function meteringSpectrum(
+  samples: Float32Array | MeteringSpectrumRequest,
+  sampleRate = 22050,
+  options: SpectrumOptions & ValidateOptions = {},
 ): SpectrumReport {
-  const validate = options?.validate !== false;
-  assertSamples('meteringSpectrum', samples, validate);
-  return requireModule().meteringSpectrum(samples, sampleRate, options ?? {});
+  const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
+  assertSamples('meteringSpectrum', request.samples, request.validate !== false);
+  return requireModule().meteringSpectrum(request.samples, request.sampleRate ?? 22050, request);
 }
 
 /**
@@ -334,47 +588,80 @@ export function meteringSpectrum(
  * time-averaged like {@link meteringSpectrum}. The analysis frame spans
  * `[frameOffset, frameOffset + nFft)`; samples past the end are zero-padded.
  */
+export function meteringSpectrumFrame(request: MeteringSpectrumFrameRequest): SpectrumReport;
 export function meteringSpectrumFrame(
   samples: Float32Array,
+  sampleRate?: number,
+  frameOffset?: number,
+  options?: SpectrumOptions & ValidateOptions,
+): SpectrumReport;
+export function meteringSpectrumFrame(
+  samples: Float32Array | MeteringSpectrumFrameRequest,
   sampleRate = 22050,
   frameOffset = 0,
-  options?: SpectrumOptions & ValidateOptions,
+  options: SpectrumOptions & ValidateOptions = {},
 ): SpectrumReport {
-  const validate = options?.validate !== false;
-  assertSamples('meteringSpectrumFrame', samples, validate);
-  return requireModule().meteringSpectrumFrame(samples, sampleRate, frameOffset, options ?? {});
+  const request =
+    samples instanceof Float32Array ? { samples, sampleRate, frameOffset, ...options } : samples;
+  assertSamples('meteringSpectrumFrame', request.samples, request.validate !== false);
+  return requireModule().meteringSpectrumFrame(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.frameOffset ?? 0,
+    request,
+  );
 }
 
 /** Compute per-channel min/max waveform buckets from interleaved audio. */
+export function waveformPeaks(request: WaveformPeaksRequest): WaveformPeaksReport;
 export function waveformPeaks(
   samples: Float32Array,
   channels: number,
+  options?: WaveformPeaksOptions,
+): WaveformPeaksReport;
+export function waveformPeaks(
+  samples: Float32Array | WaveformPeaksRequest,
+  channels?: number,
   options: WaveformPeaksOptions = {},
 ): WaveformPeaksReport {
-  assertSamples('waveformPeaks', samples, options.validate !== false);
-  if (channels <= 0 || samples.length % channels !== 0) {
+  const request =
+    samples instanceof Float32Array
+      ? { samples, channels: channels as number, ...options }
+      : samples;
+  assertSamples('waveformPeaks', request.samples, request.validate !== false);
+  if (request.channels <= 0 || request.samples.length % request.channels !== 0) {
     throw new RangeError('waveformPeaks: samples length must be a multiple of channels');
   }
-  const samplesPerBucket = options.samplesPerBucket ?? 512;
+  const samplesPerBucket = request.samplesPerBucket ?? 512;
   if (samplesPerBucket <= 0) {
     throw new RangeError('waveformPeaks: samplesPerBucket must be > 0');
   }
-  return requireModule().waveformPeaks(samples, channels, samplesPerBucket);
+  return requireModule().waveformPeaks(request.samples, request.channels, samplesPerBucket);
 }
 
 /** Compute waveform peak buckets for several zoom levels. */
+export function waveformPeakPyramid(request: WaveformPeakPyramidRequest): WaveformPeaksReport[];
 export function waveformPeakPyramid(
   samples: Float32Array,
   channels: number,
+  options?: WaveformPeakPyramidOptions,
+): WaveformPeaksReport[];
+export function waveformPeakPyramid(
+  samples: Float32Array | WaveformPeakPyramidRequest,
+  channels?: number,
   options: WaveformPeakPyramidOptions = {},
 ): WaveformPeaksReport[] {
-  assertSamples('waveformPeakPyramid', samples, options.validate !== false);
-  if (channels <= 0 || samples.length % channels !== 0) {
+  const request =
+    samples instanceof Float32Array
+      ? { samples, channels: channels as number, ...options }
+      : samples;
+  assertSamples('waveformPeakPyramid', request.samples, request.validate !== false);
+  if (request.channels <= 0 || request.samples.length % request.channels !== 0) {
     throw new RangeError('waveformPeakPyramid: samples length must be a multiple of channels');
   }
-  const levels = options.samplesPerBucketLevels ?? [512, 1024, 2048, 4096];
+  const levels = request.samplesPerBucketLevels ?? [512, 1024, 2048, 4096];
   if (levels.length === 0 || levels.some((level) => level <= 0)) {
     throw new RangeError('waveformPeakPyramid: samplesPerBucketLevels must be non-empty and > 0');
   }
-  return requireModule().waveformPeakPyramid(samples, channels, levels);
+  return requireModule().waveformPeakPyramid(request.samples, request.channels, levels);
 }

package/src/mixer.ts

@@ -55,9 +55,11 @@ export interface MixerRealtimeBuffer {
  */
 export class Mixer {
   private mixer: import('./sonare.js').WasmMixer;
+  private readonly blockSize: number;
 
-  private constructor(mixer: import('./sonare.js').WasmMixer) {
+  private constructor(mixer: import('./sonare.js').WasmMixer, blockSize: number) {
     this.mixer = mixer;
+    this.blockSize = blockSize;
   }
 
   /**
@@ -69,7 +71,7 @@ export class Mixer {
    */
   static fromSceneJson(json: string, sampleRate = 48000, blockSize = 512): Mixer {
     const module = getSonareModule();
-    return new Mixer(module.createMixerFromSceneJson(json, sampleRate, blockSize));
+    return new Mixer(module.createMixerFromSceneJson(json, sampleRate, blockSize), blockSize);
   }
 
   /** Rebuild and compile the routing graph from the current scene topology. */
@@ -536,6 +538,11 @@ export class Mixer {
    * master (`left`, `right`, `sampleRate`).
    */
   drainTailStereo(numSamples: number): MixerProcessResult {
+    if (!Number.isSafeInteger(numSamples) || numSamples <= 0 || numSamples > this.blockSize) {
+      throw new RangeError(
+        `Mixer.drainTailStereo: numSamples must be an integer in [1, ${this.blockSize}]`,
+      );
+    }
     return this.mixer.drainTailStereo(numSamples);
   }