@libraz/libsonare 1.5.2 → 1.5.3

package/src/effects_voice_change.ts

@@ -1,6 +1,5 @@
 import { getSonareModule } from './module_state';
 import type { RealtimeVoiceChangerConfigInput } from './public_types';
-import { RealtimeVoiceChanger } from './streaming_mixing';
 import type { ValidateOptions } from './validation';
 import { assertSamples } from './validation';
 
@@ -16,6 +15,12 @@ export interface VoiceChangeOptions extends ValidateOptions {
   formantFactor?: number;
 }
 
+/** Canonical request form for one-shot voice changing. */
+export interface VoiceChangeRequest extends VoiceChangeOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+}
+
 /**
  * Apply a voice change by shifting pitch and formants independently.
  *
@@ -24,17 +29,24 @@ export interface VoiceChangeOptions extends ValidateOptions {
  * @param options - Pitch/formant settings ({@link VoiceChangeOptions})
  * @returns Voice-changed audio
  */
+export function voiceChange(request: VoiceChangeRequest): Float32Array;
 export function voiceChange(
   samples: Float32Array,
+  sampleRate?: number,
+  options?: VoiceChangeOptions,
+): Float32Array;
+export function voiceChange(
+  samples: Float32Array | VoiceChangeRequest,
   sampleRate = 22050,
   options: VoiceChangeOptions = {},
 ): Float32Array {
-  assertSamples('voiceChange', samples, options.validate !== false);
+  const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
+  assertSamples('voiceChange', request.samples, request.validate !== false);
   return requireModule().voiceChange(
-    samples,
-    sampleRate,
-    options.pitchSemitones ?? 0.0,
-    options.formantFactor ?? 1.0,
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.pitchSemitones ?? 0.0,
+    request.formantFactor ?? 1.0,
   );
 }
 
@@ -42,50 +54,23 @@ export function voiceChange(
 export interface VoiceChangeRealtimeOptions extends ValidateOptions {
   /** Channel count (1 = mono, 2 = interleaved stereo). */
   channels?: 1 | 2;
-  /** Block size for the internal render loop (default 512). */
+  /** @deprecated The shared C-ABI renderer uses a fixed cross-surface block size. */
   blockSize?: number;
 }
 
-function latencyCompensatedVoiceChange(
-  changer: RealtimeVoiceChanger,
-  samples: Float32Array,
-  channels: 1 | 2,
-  blockFrames: number,
-): Float32Array {
-  const latencyFrames = Math.max(0, changer.latencySamples());
-  if (channels === 1) {
-    const total = samples.length + latencyFrames;
-    const input = new Float32Array(total);
-    input.set(samples);
-    const processed = new Float32Array(total);
-    for (let offset = 0; offset < total; offset += blockFrames) {
-      const block = input.subarray(offset, Math.min(offset + blockFrames, total));
-      processed.set(changer.processMono(block), offset);
-    }
-    return processed.slice(latencyFrames, latencyFrames + samples.length);
-  }
-
-  const frames = samples.length / 2;
-  const totalFrames = frames + latencyFrames;
-  const input = new Float32Array(totalFrames * 2);
-  input.set(samples);
-  const processed = new Float32Array(totalFrames * 2);
-  const frameStride = blockFrames * 2;
-  for (let offset = 0; offset < input.length; offset += frameStride) {
-    const block = input.subarray(offset, Math.min(offset + frameStride, input.length));
-    processed.set(changer.processInterleaved(block, 2), offset);
-  }
-  const start = latencyFrames * 2;
-  return processed.slice(start, start + samples.length);
+/** Canonical request form for offline realtime voice changing. */
+export interface VoiceChangeRealtimeRequest extends VoiceChangeRealtimeOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+  preset?: RealtimeVoiceChangerConfigInput;
 }
 
 /**
  * Applies the realtime voice-changer chain to a whole buffer in one call.
  *
- * Constructs and prepares a {@link RealtimeVoiceChanger}, runs the block loop
- * for the caller, then disposes it — matching the Python `voice_change_realtime`
- * and Node `voiceChangeRealtime` convenience wrappers. For mono, `samples` is a
- * plain mono buffer; for stereo, `samples` is interleaved (L0,R0,L1,R1,...).
+ * Uses the shared C-ABI renderer, so Python, Node, and WASM use the same
+ * fixed block size and latency compensation. For mono, `samples` is a plain
+ * buffer; for stereo, it is interleaved (L0,R0,L1,R1,...).
  *
  * @param samples - Audio samples (mono, or interleaved stereo when channels=2)
  * @param sampleRate - Sample rate in Hz (default 48000, matching Python/Node)
@@ -93,26 +78,34 @@ function latencyCompensatedVoiceChange(
  * @param options - Channel count and block size ({@link VoiceChangeRealtimeOptions})
  * @returns The processed buffer (same layout/length as the input).
  */
+export function voiceChangeRealtime(request: VoiceChangeRealtimeRequest): Float32Array;
 export function voiceChangeRealtime(
   samples: Float32Array,
+  sampleRate?: number,
+  preset?: RealtimeVoiceChangerConfigInput,
+  options?: VoiceChangeRealtimeOptions,
+): Float32Array;
+export function voiceChangeRealtime(
+  samples: Float32Array | VoiceChangeRealtimeRequest,
   sampleRate = 48000,
   preset: RealtimeVoiceChangerConfigInput = 'neutral-monitor',
   options: VoiceChangeRealtimeOptions = {},
 ): Float32Array {
-  assertSamples('voiceChangeRealtime', samples, options.validate !== false);
-  const channels = options.channels ?? 1;
+  const request =
+    samples instanceof Float32Array ? { samples, sampleRate, preset, ...options } : samples;
+  assertSamples('voiceChangeRealtime', request.samples, request.validate !== false);
+  const channels = request.channels ?? 1;
   if (channels !== 1 && channels !== 2) {
     throw new Error('voiceChangeRealtime: channels must be 1 or 2.');
   }
-  if (channels === 2 && samples.length % 2 !== 0) {
+  if (channels === 2 && request.samples.length % 2 !== 0) {
     throw new Error('voiceChangeRealtime: stereo input length must be a multiple of 2.');
   }
-  const blockSize = Math.max(1, Math.floor(options.blockSize ?? 512));
-  const changer = new RealtimeVoiceChanger(preset);
-  try {
-    changer.prepare(sampleRate, blockSize, channels);
-    return latencyCompensatedVoiceChange(changer, samples, channels, blockSize);
-  } finally {
-    changer.delete();
-  }
+  const presetConfig = request.preset ?? 'neutral-monitor';
+  return requireModule().voiceChangeRealtime(
+    request.samples,
+    request.sampleRate ?? 48000,
+    typeof presetConfig === 'string' ? presetConfig : JSON.stringify(presetConfig),
+    channels,
+  );
 }

package/src/feature_core.ts

@@ -11,6 +11,102 @@ function requireModule() {
   return getSonareModule();
 }
 
+export interface DbConversionRequest {
+  values: Float32Array;
+  ref?: number;
+  amin?: number;
+  topDb?: number;
+}
+
+export interface SilenceRequest {
+  samples: Float32Array;
+  topDb?: number;
+  frameLength?: number;
+  hopLength?: number;
+}
+
+export interface FrameSignalRequest {
+  samples: Float32Array;
+  frameLength: number;
+  hopLength: number;
+}
+/** Canonical request form for pre/de-emphasis filters. */
+export interface EmphasisRequest {
+  samples: Float32Array;
+  coef?: number;
+  zi?: number;
+}
+/** Canonical request form for centering or extending a vector. */
+export interface PadCenterRequest {
+  values: Float32Array;
+  targetSize: number;
+  padValue?: number;
+}
+/** Canonical request form for resizing a vector. */
+export interface FixLengthRequest {
+  values: Float32Array;
+  targetSize: number;
+  padValue?: number;
+}
+/** Canonical request form for bounding a frame-index vector. */
+export interface FixFramesRequest {
+  frames: Int32Array;
+  xMin?: number;
+  xMax?: number;
+  pad?: boolean;
+}
+/** Canonical request form for peak selection. */
+export interface PeakPickRequest {
+  values: Float32Array;
+  preMax: number;
+  postMax: number;
+  preAvg: number;
+  postAvg: number;
+  delta: number;
+  wait: number;
+}
+/** Canonical request form for vector normalization. */
+export interface VectorNormalizeRequest {
+  values: Float32Array;
+  normType?: number;
+  threshold?: number;
+}
+/** Canonical request form for tonal centroid projection. */
+export interface TonnetzRequest {
+  chromagram: Float32Array;
+  nChroma: number;
+  nFrames: number;
+}
+export interface PcenRequest {
+  values: Float32Array;
+  nBins: number;
+  nFrames: number;
+  options?: Record<string, number>;
+}
+export interface TempogramRequest {
+  onsetEnvelope: Float32Array;
+  sampleRate?: number;
+  hopLength?: number;
+  winLength?: number;
+  mode?: TempogramMode;
+}
+export interface CyclicTempogramRequest {
+  onsetEnvelope: Float32Array;
+  sampleRate?: number;
+  hopLength?: number;
+  winLength?: number;
+  bpmMin?: number;
+  nBins?: number;
+}
+export interface PlpRequest {
+  onsetEnvelope: Float32Array;
+  sampleRate?: number;
+  hopLength?: number;
+  tempoMin?: number;
+  tempoMax?: number;
+  winLength?: number;
+}
+
 // ============================================================================
 // Core - Unit Conversion
 // ============================================================================
@@ -107,21 +203,41 @@ export function samplesToFrames(samples: number, hopLength = 512, nFft = 0): num
   return requireModule().samplesToFrames(samples, hopLength, nFft);
 }
 
+export function powerToDb(request: DbConversionRequest): Float32Array;
 export function powerToDb(
   values: Float32Array,
+  ref?: number,
+  amin?: number,
+  topDb?: number,
+): Float32Array;
+export function powerToDb(
+  values: Float32Array | DbConversionRequest,
   ref = 1.0,
   amin = 1e-10,
   topDb = 80.0,
 ): Float32Array {
+  if (!(values instanceof Float32Array)) {
+    return powerToDb(values.values, values.ref, values.amin, values.topDb);
+  }
   return requireModule().powerToDb(values, ref, amin, topDb);
 }
 
+export function amplitudeToDb(request: DbConversionRequest): Float32Array;
 export function amplitudeToDb(
   values: Float32Array,
+  ref?: number,
+  amin?: number,
+  topDb?: number,
+): Float32Array;
+export function amplitudeToDb(
+  values: Float32Array | DbConversionRequest,
   ref = 1.0,
   amin = 1e-5,
   topDb = 80.0,
 ): Float32Array {
+  if (!(values instanceof Float32Array)) {
+    return amplitudeToDb(values.values, values.ref, values.amin, values.topDb);
+  }
   return requireModule().amplitudeToDb(values, ref, amin, topDb);
 }
 
@@ -133,52 +249,141 @@ export function dbToAmplitude(values: Float32Array, ref = 1.0): Float32Array {
   return requireModule().dbToAmplitude(values, ref);
 }
 
-export function preemphasis(samples: Float32Array, coef = 0.97, zi?: number): Float32Array {
+export function preemphasis(request: EmphasisRequest): Float32Array;
+export function preemphasis(samples: Float32Array, coef?: number, zi?: number): Float32Array;
+export function preemphasis(
+  samples: Float32Array | EmphasisRequest,
+  coef = 0.97,
+  zi?: number,
+): Float32Array {
+  if (!(samples instanceof Float32Array)) {
+    return preemphasis(samples.samples, samples.coef, samples.zi);
+  }
   return requireModule().preemphasis(samples, coef, zi ?? null);
 }
 
-export function deemphasis(samples: Float32Array, coef = 0.97, zi?: number): Float32Array {
+export function deemphasis(request: EmphasisRequest): Float32Array;
+export function deemphasis(samples: Float32Array, coef?: number, zi?: number): Float32Array;
+export function deemphasis(
+  samples: Float32Array | EmphasisRequest,
+  coef = 0.97,
+  zi?: number,
+): Float32Array {
+  if (!(samples instanceof Float32Array)) {
+    return deemphasis(samples.samples, samples.coef, samples.zi);
+  }
   return requireModule().deemphasis(samples, coef, zi ?? null);
 }
 
+export function trimSilence(request: SilenceRequest): WasmTrimResult;
 export function trimSilence(
   samples: Float32Array,
+  topDb?: number,
+  frameLength?: number,
+  hopLength?: number,
+): WasmTrimResult;
+export function trimSilence(
+  samples: Float32Array | SilenceRequest,
   topDb = 60.0,
   frameLength = 2048,
   hopLength = 512,
 ): WasmTrimResult {
+  if (!(samples instanceof Float32Array)) {
+    return trimSilence(samples.samples, samples.topDb, samples.frameLength, samples.hopLength);
+  }
   return requireModule().trimSilence(samples, topDb, frameLength, hopLength);
 }
 
+export function splitSilence(request: SilenceRequest): Int32Array;
 export function splitSilence(
   samples: Float32Array,
+  topDb?: number,
+  frameLength?: number,
+  hopLength?: number,
+): Int32Array;
+export function splitSilence(
+  samples: Float32Array | SilenceRequest,
   topDb = 60.0,
   frameLength = 2048,
   hopLength = 512,
 ): Int32Array {
+  if (!(samples instanceof Float32Array)) {
+    return splitSilence(samples.samples, samples.topDb, samples.frameLength, samples.hopLength);
+  }
   return requireModule().splitSilence(samples, topDb, frameLength, hopLength);
 }
 
+export function frameSignal(request: FrameSignalRequest): WasmFrameResult;
 export function frameSignal(
   samples: Float32Array,
   frameLength: number,
   hopLength: number,
+): WasmFrameResult;
+export function frameSignal(
+  samples: Float32Array | FrameSignalRequest,
+  frameLength?: number,
+  hopLength?: number,
 ): WasmFrameResult {
-  return requireModule().frameSignal(samples, frameLength, hopLength);
+  if (!(samples instanceof Float32Array)) {
+    return frameSignal(samples.samples, samples.frameLength, samples.hopLength);
+  }
+  return requireModule().frameSignal(samples, frameLength as number, hopLength as number);
 }
 
-export function padCenter(values: Float32Array, targetSize: number, padValue = 0.0): Float32Array {
-  return requireModule().padCenter(values, targetSize, padValue);
+export function padCenter(request: PadCenterRequest): Float32Array;
+export function padCenter(
+  values: Float32Array,
+  targetSize: number,
+  padValue?: number,
+): Float32Array;
+export function padCenter(
+  values: Float32Array | PadCenterRequest,
+  targetSize?: number,
+  padValue = 0.0,
+): Float32Array {
+  if (!(values instanceof Float32Array)) {
+    return padCenter(values.values, values.targetSize, values.padValue);
+  }
+  return requireModule().padCenter(values, targetSize as number, padValue);
 }
 
-export function fixLength(values: Float32Array, targetSize: number, padValue = 0.0): Float32Array {
-  return requireModule().fixLength(values, targetSize, padValue);
+export function fixLength(request: FixLengthRequest): Float32Array;
+export function fixLength(
+  values: Float32Array,
+  targetSize: number,
+  padValue?: number,
+): Float32Array;
+export function fixLength(
+  values: Float32Array | FixLengthRequest,
+  targetSize?: number,
+  padValue = 0.0,
+): Float32Array {
+  if (!(values instanceof Float32Array)) {
+    return fixLength(values.values, values.targetSize, values.padValue);
+  }
+  return requireModule().fixLength(values, targetSize as number, padValue);
 }
 
-export function fixFrames(frames: Int32Array, xMin = 0, xMax = -1, pad = true): Int32Array {
+export function fixFrames(request: FixFramesRequest): Int32Array;
+export function fixFrames(
+  frames: Int32Array,
+  xMin?: number,
+  xMax?: number,
+  pad?: boolean,
+): Int32Array;
+export function fixFrames(
+  frames: Int32Array | FixFramesRequest,
+  xMin = 0,
+  xMax = -1,
+  pad = true,
+): Int32Array {
+  if (!(frames instanceof Int32Array)) {
+    return fixFrames(frames.frames, frames.xMin, frames.xMax, frames.pad);
+  }
   return requireModule().fixFrames(frames, xMin, xMax, pad);
 }
 
+export function peakPick(request: PeakPickRequest): Int32Array;
 export function peakPick(
   values: Float32Array,
   preMax: number,
@@ -187,45 +392,131 @@ export function peakPick(
   postAvg: number,
   delta: number,
   wait: number,
+): Int32Array;
+export function peakPick(
+  values: Float32Array | PeakPickRequest,
+  preMax?: number,
+  postMax?: number,
+  preAvg?: number,
+  postAvg?: number,
+  delta?: number,
+  wait?: number,
 ): Int32Array {
-  return requireModule().peakPick(values, preMax, postMax, preAvg, postAvg, delta, wait);
+  if (!(values instanceof Float32Array)) {
+    const r = values;
+    return peakPick(r.values, r.preMax, r.postMax, r.preAvg, r.postAvg, r.delta, r.wait);
+  }
+  return requireModule().peakPick(
+    values,
+    preMax as number,
+    postMax as number,
+    preAvg as number,
+    postAvg as number,
+    delta as number,
+    wait as number,
+  );
 }
 
-export function vectorNormalize(values: Float32Array, normType = 0, threshold = 0.0): Float32Array {
+export function vectorNormalize(request: VectorNormalizeRequest): Float32Array;
+export function vectorNormalize(
+  values: Float32Array,
+  normType?: number,
+  threshold?: number,
+): Float32Array;
+export function vectorNormalize(
+  values: Float32Array | VectorNormalizeRequest,
+  normType = 0,
+  threshold = 0.0,
+): Float32Array {
+  if (!(values instanceof Float32Array)) {
+    return vectorNormalize(values.values, values.normType, values.threshold);
+  }
   return requireModule().vectorNormalize(values, normType, threshold);
 }
 
+export function pcen(request: PcenRequest): Float32Array;
 export function pcen(
   values: Float32Array,
   nBins: number,
   nFrames: number,
+  options?: Record<string, number>,
+): Float32Array;
+export function pcen(
+  values: Float32Array | PcenRequest,
+  nBins = 0,
+  nFrames = 0,
   options: Record<string, number> = {},
 ): Float32Array {
+  if (!(values instanceof Float32Array)) {
+    const r = values;
+    return pcen(r.values, r.nBins, r.nFrames, r.options);
+  }
   return requireModule().pcen(values, nBins, nFrames, options);
 }
 
-export function tonnetz(chromagram: Float32Array, nChroma: number, nFrames: number): Float32Array {
-  return requireModule().tonnetz(chromagram, nChroma, nFrames);
+export function tonnetz(request: TonnetzRequest): Float32Array;
+export function tonnetz(chromagram: Float32Array, nChroma: number, nFrames: number): Float32Array;
+export function tonnetz(
+  chromagram: Float32Array | TonnetzRequest,
+  nChroma?: number,
+  nFrames?: number,
+): Float32Array {
+  if (!(chromagram instanceof Float32Array)) {
+    return tonnetz(chromagram.chromagram, chromagram.nChroma, chromagram.nFrames);
+  }
+  return requireModule().tonnetz(chromagram, nChroma as number, nFrames as number);
 }
 
+export function tempogram(request: TempogramRequest): WasmTempogramResult;
 export function tempogram(
   onsetEnvelope: Float32Array,
+  sampleRate?: number,
+  hopLength?: number,
+  winLength?: number,
+  mode?: TempogramMode,
+): WasmTempogramResult;
+export function tempogram(
+  onsetEnvelope: Float32Array | TempogramRequest,
   sampleRate = 22050,
   hopLength = 512,
   winLength = 384,
   mode: TempogramMode = 'autocorrelation',
 ): WasmTempogramResult {
+  if (!(onsetEnvelope instanceof Float32Array)) {
+    const r = onsetEnvelope;
+    return tempogram(r.onsetEnvelope, r.sampleRate, r.hopLength, r.winLength, r.mode);
+  }
   return requireModule().tempogram(onsetEnvelope, sampleRate, hopLength, winLength, mode);
 }
 
+export function cyclicTempogram(request: CyclicTempogramRequest): WasmCyclicTempogramResult;
 export function cyclicTempogram(
   onsetEnvelope: Float32Array,
+  sampleRate?: number,
+  hopLength?: number,
+  winLength?: number,
+  bpmMin?: number,
+  nBins?: number,
+): WasmCyclicTempogramResult;
+export function cyclicTempogram(
+  onsetEnvelope: Float32Array | CyclicTempogramRequest,
   sampleRate = 22050,
   hopLength = 512,
   winLength = 384,
   bpmMin = 60.0,
   nBins = 60,
 ): WasmCyclicTempogramResult {
+  if (!(onsetEnvelope instanceof Float32Array)) {
+    const r = onsetEnvelope;
+    return cyclicTempogram(
+      r.onsetEnvelope,
+      r.sampleRate,
+      r.hopLength,
+      r.winLength,
+      r.bpmMin,
+      r.nBins,
+    );
+  }
   return requireModule().cyclicTempogram(
     onsetEnvelope,
     sampleRate,
@@ -236,13 +527,26 @@ export function cyclicTempogram(
   );
 }
 
+export function plp(request: PlpRequest): Float32Array;
 export function plp(
   onsetEnvelope: Float32Array,
+  sampleRate?: number,
+  hopLength?: number,
+  tempoMin?: number,
+  tempoMax?: number,
+  winLength?: number,
+): Float32Array;
+export function plp(
+  onsetEnvelope: Float32Array | PlpRequest,
   sampleRate = 22050,
   hopLength = 512,
   tempoMin = 30.0,
   tempoMax = 300.0,
   winLength = 384,
 ): Float32Array {
+  if (!(onsetEnvelope instanceof Float32Array)) {
+    const r = onsetEnvelope;
+    return plp(r.onsetEnvelope, r.sampleRate, r.hopLength, r.tempoMin, r.tempoMax, r.winLength);
+  }
   return requireModule().plp(onsetEnvelope, sampleRate, hopLength, tempoMin, tempoMax, winLength);
 }