@libraz/libsonare 1.2.2 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "type": "module",
   "packageManager": "yarn@4.15.0",
   "description": "Audio analysis library for music information retrieval",

package/src/index.ts

@@ -3,7 +3,7 @@
  *
  * @example
  * ```typescript
- * import { init, detectBpm, detectKey, analyze } from '@libraz/sonare';
+ * import { init, detectBpm, detectKey, analyze } from '@libraz/libsonare';
  *
  * await init();
  *
@@ -60,6 +60,11 @@ import type {
   PitchResult,
   RealtimeVoiceChangerConfigInput,
   RealtimeVoiceChangerPodConfig,
+  RirResult,
+  RirSynthOptions,
+  RoomEstimateOptions,
+  RoomEstimateResult,
+  RoomMorphOptions,
   Section,
   SectionType,
   SendTiming,
@@ -151,6 +156,7 @@ export type {
   MasteringStereoResult,
   MelodyPoint,
   MelodyResult,
+  MelPowerResult,
   MelSpectrogramResult,
   MeterTap,
   MfccResult,
@@ -164,15 +170,24 @@ export type {
   PanMode,
   PitchResult,
   RealtimeVoiceChangerConfigInput,
+  RealtimeVoiceChangerPodConfig,
   RhythmFeatures,
+  RirResult,
+  RirSynthOptions,
+  RoomEstimateOptions,
+  RoomEstimateResult,
+  RoomGeometryOptions,
+  RoomMorphOptions,
   Section,
   SendTiming,
   SoloProcessor,
   StereoAnalysis,
+  StftPowerResult,
   StftResult,
   StreamingEqualizerConfig,
   StreamingPlatform,
   StreamingRetuneConfig,
+  TempogramMode,
   Timbre,
   TimeSignature,
   VoicePresetId,
@@ -712,6 +727,34 @@ export class RealtimeEngine {
     return this.native.process(channels);
   }
 
+  /**
+   * Allocates persistent per-channel WASM-heap scratch for the zero-copy
+   * `getChannelBuffer` / `processPrepared` realtime path. Call once (off the
+   * audio thread) before driving `processPrepared` from an AudioWorklet so the
+   * render callback never allocates on the C++/JS heap.
+   */
+  prepareChannels(numChannels: number, maxFrames: number): void {
+    this.native.prepareChannels(numChannels, maxFrames);
+  }
+
+  /**
+   * Returns a Float32Array view onto the persistent WASM-heap scratch for one
+   * channel (valid for up to `numFrames`). Fill it, call `processPrepared`, then
+   * read the same view back. Re-acquire after WASM memory growth.
+   */
+  getChannelBuffer(channel: number, numFrames: number): Float32Array {
+    return this.native.getChannelBuffer(channel, numFrames);
+  }
+
+  /**
+   * Runs the engine in place over the prepared per-channel scratch buffers.
+   * Allocation-free: safe to call on the AudioWorklet render thread after
+   * `prepareChannels`.
+   */
+  processPrepared(numFrames: number): void {
+    this.native.processPrepared(numFrames);
+  }
+
   processWithMonitor(channels: Float32Array[]): WasmEngineProcessWithMonitorResult {
     return this.native.processWithMonitor(channels);
   }
@@ -1086,6 +1129,57 @@ export function detectAcoustic(
   return result;
 }
 
+/**
+ * Synthesize a room impulse response from shoebox geometry. `hasError` is true
+ * when the source/listener falls outside the room (the RIR is then empty).
+ */
+export function synthesizeRir(options: RirSynthOptions = {}): RirResult {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  if (typeof module.synthesizeRir !== 'function') {
+    throw new Error('libsonare was built without acoustic-simulation support');
+  }
+  return module.synthesizeRir(options);
+}
+
+/**
+ * Estimate an equivalent room (volume/dimensions/absorption/DRR) from a
+ * recording or impulse response.
+ */
+export function estimateRoom(
+  samples: Float32Array,
+  sampleRate = 48000,
+  options: RoomEstimateOptions = {},
+): RoomEstimateResult {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  if (typeof module.estimateRoom !== 'function') {
+    throw new Error('libsonare was built without acoustic-simulation support');
+  }
+  return module.estimateRoom(samples, sampleRate, options);
+}
+
+/**
+ * Morph a recording's reverberation toward a target room (creative FX, not
+ * dereverberation). Returns the morphed samples (input length plus the target
+ * room's reverb tail).
+ */
+export function roomMorph(
+  samples: Float32Array,
+  sampleRate: number,
+  options: RoomMorphOptions = {},
+): Float32Array {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  if (typeof module.roomMorph !== 'function') {
+    throw new Error('libsonare was built without acoustic-simulation support');
+  }
+  return module.roomMorph(samples, sampleRate, options);
+}
+
 /**
  * Perform complete music analysis with progress reporting.
  *
@@ -1286,10 +1380,15 @@ export function hpss(
  * @param sampleRate - Sample rate in Hz
  * @returns Harmonic component
  */
-export function harmonic(samples: Float32Array, sampleRate: number): Float32Array {
+export function harmonic(
+  samples: Float32Array,
+  sampleRate: number,
+  options: ValidateOptions = {},
+): Float32Array {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
+  assertSamples('harmonic', samples, options.validate !== false);
   return module.harmonic(samples, sampleRate);
 }
 
@@ -1300,10 +1399,15 @@ export function harmonic(samples: Float32Array, sampleRate: number): Float32Arra
  * @param sampleRate - Sample rate in Hz
  * @returns Percussive component
  */
-export function percussive(samples: Float32Array, sampleRate: number): Float32Array {
+export function percussive(
+  samples: Float32Array,
+  sampleRate: number,
+  options: ValidateOptions = {},
+): Float32Array {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
+  assertSamples('percussive', samples, options.validate !== false);
   return module.percussive(samples, sampleRate);
 }
 
@@ -1315,10 +1419,16 @@ export function percussive(samples: Float32Array, sampleRate: number): Float32Ar
  * @param rate - Time stretch rate (0.5 = double duration, 2.0 = half duration)
  * @returns Time-stretched audio
  */
-export function timeStretch(samples: Float32Array, sampleRate: number, rate: number): Float32Array {
+export function timeStretch(
+  samples: Float32Array,
+  sampleRate: number,
+  rate: number,
+  options: ValidateOptions = {},
+): Float32Array {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
+  assertSamples('timeStretch', samples, options.validate !== false);
   return module.timeStretch(samples, sampleRate, rate);
 }
 
@@ -1334,10 +1444,12 @@ export function pitchShift(
   samples: Float32Array,
   sampleRate: number,
   semitones: number,
+  options: ValidateOptions = {},
 ): Float32Array {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
+  assertSamples('pitchShift', samples, options.validate !== false);
   return module.pitchShift(samples, sampleRate, semitones);
 }
 
@@ -1355,10 +1467,12 @@ export function pitchCorrectToMidi(
   sampleRate = 22050,
   currentMidi = 69.0,
   targetMidi = 69.0,
+  options: ValidateOptions = {},
 ): Float32Array {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
+  assertSamples('pitchCorrectToMidi', samples, options.validate !== false);
   return module.pitchCorrectToMidi(samples, sampleRate, currentMidi, targetMidi);
 }
 
@@ -1378,10 +1492,12 @@ export function noteStretch(
   onsetSample = 0,
   offsetSample = 0,
   stretchRatio = 1.0,
+  options: ValidateOptions = {},
 ): Float32Array {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
+  assertSamples('noteStretch', samples, options.validate !== false);
   return module.noteStretch(samples, sampleRate, onsetSample, offsetSample, stretchRatio);
 }
 
@@ -1408,6 +1524,65 @@ export function voiceChange(
   return module.voiceChange(samples, sampleRate, pitchSemitones, formantFactor);
 }
 
+/** Options for the offline {@link voiceChangeRealtime} convenience wrapper. */
+export interface VoiceChangeRealtimeOptions extends ValidateOptions {
+  sampleRate?: number;
+  /** Voice-changer preset id or full config object. */
+  preset?: RealtimeVoiceChangerConfigInput;
+  /** Channel count (1 = mono, 2 = interleaved stereo). */
+  channels?: 1 | 2;
+  /** Block size for the internal render loop (default 512). */
+  blockSize?: number;
+}
+
+/**
+ * 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,...).
+ *
+ * @returns The processed buffer (same layout/length as the input).
+ */
+export function voiceChangeRealtime(
+  samples: Float32Array,
+  options: VoiceChangeRealtimeOptions = {},
+): Float32Array {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  assertSamples('voiceChangeRealtime', samples, options.validate !== false);
+  const channels = options.channels ?? 1;
+  if (channels !== 1 && channels !== 2) {
+    throw new Error('voiceChangeRealtime: channels must be 1 or 2.');
+  }
+  // 48000 matches the Python voice_change_realtime and Node voiceChangeRealtime
+  // convenience wrappers (and the RealtimeVoiceChanger default).
+  const sampleRate = options.sampleRate ?? 48000;
+  const blockSize = Math.max(1, Math.floor(options.blockSize ?? 512));
+  const changer = new RealtimeVoiceChanger(options.preset ?? 'neutral-monitor');
+  try {
+    changer.prepare(sampleRate, blockSize, channels);
+    const out = new Float32Array(samples.length);
+    if (channels === 1) {
+      for (let offset = 0; offset < samples.length; offset += blockSize) {
+        const block = samples.subarray(offset, Math.min(offset + blockSize, samples.length));
+        out.set(changer.processMono(block), offset);
+      }
+    } else {
+      const frameStride = blockSize * 2;
+      for (let offset = 0; offset < samples.length; offset += frameStride) {
+        const block = samples.subarray(offset, Math.min(offset + frameStride, samples.length));
+        out.set(changer.processInterleaved(block, 2), offset);
+      }
+    }
+    return out;
+  } finally {
+    changer.delete();
+  }
+}
+
 /**
  * Normalize audio to target peak level.
  *
@@ -1416,10 +1591,16 @@ export function voiceChange(
  * @param targetDb - Target peak level in dB (default: 0 dB = full scale)
  * @returns Normalized audio
  */
-export function normalize(samples: Float32Array, sampleRate: number, targetDb = 0.0): Float32Array {
+export function normalize(
+  samples: Float32Array,
+  sampleRate: number,
+  targetDb = 0.0,
+  options: ValidateOptions = {},
+): Float32Array {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
+  assertSamples('normalize', samples, options.validate !== false);
   return module.normalize(samples, sampleRate, targetDb);
 }
 
@@ -4535,7 +4716,7 @@ export function resample(samples: Float32Array, srcSr: number, targetSr: number)
  *
  * @example
  * ```typescript
- * import { init, Audio } from '@libraz/sonare';
+ * import { init, Audio } from '@libraz/libsonare';
  *
  * await init();
  *
@@ -4802,7 +4983,7 @@ export class Audio {
  *
  * @example
  * ```typescript
- * import { init, StreamAnalyzer } from '@libraz/sonare';
+ * import { init, StreamAnalyzer } from '@libraz/libsonare';
  *
  * await init();
  *
@@ -4831,7 +5012,7 @@ export class StreamAnalyzer {
       throw new Error('Module not initialized. Call init() first.');
     }
     this.analyzer = new module.StreamAnalyzer(
-      config.sampleRate,
+      config.sampleRate ?? 44100,
       config.nFft ?? 2048,
       config.hopLength ?? 512,
       config.nMels ?? 128,

package/src/public_types.ts

@@ -421,6 +421,69 @@ export interface AcousticResult {
   isBlind: boolean;
 }
 
+/** Shoebox geometry + placement shared by RIR synthesis and the room morph. */
+export interface RoomGeometryOptions {
+  lengthM?: number;
+  widthM?: number;
+  heightM?: number;
+  absorption?: number;
+  sourceX?: number;
+  sourceY?: number;
+  sourceZ?: number;
+  listenerX?: number;
+  listenerY?: number;
+  listenerZ?: number;
+  ismOrder?: number;
+  seed?: number;
+  maxSeconds?: number;
+}
+
+export interface RirSynthOptions extends RoomGeometryOptions {
+  sampleRate?: number;
+  /** Use the Eyring statistical late-tail model (default true); false = Sabine. */
+  preferEyring?: boolean;
+  /** Early/late crossover in ms (0 = auto, ~sqrt(V) ms). */
+  mixingTimeMs?: number;
+  /** Equal-power crossfade width around the mixing time in ms (0 = default). */
+  crossfadeMs?: number;
+}
+
+export interface RirResult {
+  rir: Float32Array;
+  sampleRate: number;
+  hasError: boolean;
+}
+
+export interface RoomEstimateOptions {
+  aspectHintLw?: number;
+  aspectHintLh?: number;
+  referenceAbsorption?: number;
+  preferEyring?: boolean;
+  nOctaveBands?: number;
+  /** Analyzer routing: 0 = auto, 1 = blind, 2 = impulse-response. */
+  mode?: number;
+  /** Analyzer decay-fit span in dB (0 = library default). */
+  minDecayDb?: number;
+  /** Analyzer noise-floor margin in dB (0 = library default). */
+  noiseFloorMarginDb?: number;
+}
+
+export interface RoomEstimateResult {
+  volume: number;
+  length: number;
+  width: number;
+  height: number;
+  drrDb: number;
+  confidence: number;
+  absorptionBands: Float32Array;
+  rt60Bands: Float32Array;
+}
+
+export interface RoomMorphOptions extends RoomGeometryOptions {
+  wet?: number;
+  sourceTailSuppression?: number;
+}
+
 /**
  * HPSS (Harmonic-Percussive Source Separation) result
  */
@@ -914,6 +977,10 @@ export interface RealtimeVoiceChangerPodConfig {
   reverb_seed: number;
   limiter_ceiling_db: number;
   limiter_release_ms: number;
+  /** Non-zero enables the 4x-oversampled inter-sample-peak limiter (default enabled). */
+  limiter_enable_isp_limiter: boolean;
+  /** True-peak ceiling in dBTP applied by the ISP limiter (default -1.0). */
+  limiter_isp_ceiling_dbtp: number;
 }
 
 /** Options for {@link StreamingEqualizer.match}. */

package/src/sonare.js.d.ts

@@ -60,6 +60,8 @@ export interface WasmRealtimeVoiceChangerPodConfig {
   reverb_seed: number;
   limiter_ceiling_db: number;
   limiter_release_ms: number;
+  limiter_enable_isp_limiter: boolean;
+  limiter_isp_ceiling_dbtp: number;
 }
 
 export interface WasmBeatResult {
@@ -199,6 +201,62 @@ export interface WasmAcousticResult {
   isBlind: boolean;
 }
 
+export interface WasmRoomGeometryOptions {
+  lengthM?: number;
+  widthM?: number;
+  heightM?: number;
+  absorption?: number;
+  sourceX?: number;
+  sourceY?: number;
+  sourceZ?: number;
+  listenerX?: number;
+  listenerY?: number;
+  listenerZ?: number;
+  ismOrder?: number;
+  seed?: number;
+  maxSeconds?: number;
+}
+
+export interface WasmRirSynthOptions extends WasmRoomGeometryOptions {
+  sampleRate?: number;
+  preferEyring?: boolean;
+  mixingTimeMs?: number;
+  crossfadeMs?: number;
+}
+
+export interface WasmRirResult {
+  rir: Float32Array;
+  sampleRate: number;
+  hasError: boolean;
+}
+
+export interface WasmRoomEstimateOptions {
+  aspectHintLw?: number;
+  aspectHintLh?: number;
+  referenceAbsorption?: number;
+  preferEyring?: boolean;
+  nOctaveBands?: number;
+  mode?: number;
+  minDecayDb?: number;
+  noiseFloorMarginDb?: number;
+}
+
+export interface WasmRoomEstimateResult {
+  volume: number;
+  length: number;
+  width: number;
+  height: number;
+  drrDb: number;
+  confidence: number;
+  absorptionBands: Float32Array;
+  rt60Bands: Float32Array;
+}
+
+export interface WasmRoomMorphOptions extends WasmRoomGeometryOptions {
+  wet?: number;
+  sourceTailSuppression?: number;
+}
+
 export interface WasmHpssResult {
   harmonic: Float32Array;
   percussive: Float32Array;
@@ -450,6 +508,8 @@ export interface WasmEngineMetronomeConfig {
   beatGain?: number;
   accentGain?: number;
   clickSamples?: number;
+  /** Optional click length in seconds; > 0 overrides the engine 2 ms default. */
+  clickSeconds?: number;
 }
 
 export interface WasmEngineGraphNode {
@@ -528,6 +588,12 @@ export interface WasmEngineTransportState {
   loopStartPpq: number;
   loopEndPpq: number;
   sampleRate: number;
+  /** PPQ of the current bar's downbeat (derived from the tempo map). */
+  barStartPpq: number;
+  /** Zero-based index of the current bar. */
+  barCount: number;
+  /** Time signature in effect at the current PPQ. */
+  timeSignature: { numerator: number; denominator: number; confidence: number };
 }
 
 export interface WasmEngineBounceOptions {
@@ -615,6 +681,9 @@ export interface WasmRealtimeEngine {
   captureStatus: () => WasmEngineCaptureStatus;
   capturedAudio: () => Float32Array[];
   process: (channels: Float32Array[]) => Float32Array[];
+  prepareChannels: (numChannels: number, maxFrames: number) => void;
+  getChannelBuffer: (channel: number, numFrames: number) => Float32Array;
+  processPrepared: (numFrames: number) => void;
   processWithMonitor: (channels: Float32Array[]) => WasmEngineProcessWithMonitorResult;
   renderOffline: (channels: Float32Array[], blockSize: number) => Float32Array[];
   bounceOffline: (options: WasmEngineBounceOptions) => WasmEngineBounceResult;
@@ -690,6 +759,19 @@ export interface SonareModule {
     minDecayDb: number,
     noiseFloorMarginDb: number,
   ) => WasmAcousticResult;
+  // Acoustic-simulation entry points are present only in builds compiled with
+  // SONARE_WITH_ACOUSTIC_SIM; absent otherwise (the wrappers throw a clear error).
+  synthesizeRir?: (options: WasmRirSynthOptions) => WasmRirResult;
+  estimateRoom?: (
+    samples: Float32Array,
+    sampleRate: number,
+    options: WasmRoomEstimateOptions,
+  ) => WasmRoomEstimateResult;
+  roomMorph?: (
+    samples: Float32Array,
+    sampleRate: number,
+    options: WasmRoomMorphOptions,
+  ) => Float32Array;
   analyzeWithProgress: (
     samples: Float32Array,
     sampleRate: number,
@@ -1703,6 +1785,8 @@ export interface WasmAnalyzerStats {
 
 export interface WasmFrameBuffer {
   nFrames: number;
+  /** Number of mel bands; flat `mel` is `[nFrames * nMels]` row-major. */
+  nMels: number;
   timestamps: Float32Array;
   mel: Float32Array;
   chroma: Float32Array;

package/src/stream_types.ts

@@ -72,6 +72,8 @@ export interface AnalyzerStats {
  */
 export interface FrameBuffer {
   nFrames: number;
+  /** Number of mel bands; flat `mel` is `[nFrames * nMels]` row-major. */
+  nMels: number;
   timestamps: Float32Array;
   mel: Float32Array;
   chroma: Float32Array;
@@ -112,7 +114,8 @@ export interface StreamFramesI16 {
  * Configuration for StreamAnalyzer
  */
 export interface StreamConfig {
-  sampleRate: number;
+  /** Sample rate in Hz. Optional for parity with the Node/Python bindings (default 44100). */
+  sampleRate?: number;
   nFft?: number;
   hopLength?: number;
   nMels?: number;