@libraz/libsonare 1.5.0 → 1.5.1

package/package.json

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

package/src/clip_page_streamer.ts

@@ -47,8 +47,12 @@ export interface ClipPageStreamerOptions {
 interface SourceState {
   source: ClipPageStreamSource;
   lastPage: number;
-  /** Page indices currently supplied to the provider (the resident set). */
-  resident: Set<number>;
+  /** Playback-window generation; advanced on reset or backward discontinuity. */
+  generation: number;
+  /** Most recently serviced playback frontier, or null before the first miss. */
+  lastFrontier: number | null;
+  /** Resident page -> generation, so in-flight stale fetches cannot alias. */
+  resident: Map<number, number>;
 }
 
 /**
@@ -92,18 +96,40 @@ export class ClipPageStreamer {
       throw new Error('pageFrames and numSamples must be positive');
     }
     const lastPage = Math.ceil(source.numSamples / source.pageFrames) - 1;
+    const previous = this.sources.get(source.clipId);
+    if (previous) {
+      this.resetState(previous);
+    }
     this.sources.set(source.clipId, {
       source,
       lastPage,
-      resident: new Set(initialResidentPages),
+      generation: 0,
+      lastFrontier: null,
+      resident: new Map(Array.from(initialResidentPages, (page) => [page, 0])),
     });
   }
 
   /** Stop tracking a clip. Does not close its binding (the caller owns that). */
   removeSource(clipId: number): void {
+    const state = this.sources.get(clipId);
+    if (state) {
+      this.resetState(state);
+    }
     this.sources.delete(clipId);
   }
 
+  /**
+   * Explicitly start a new playback generation after a host seek/loop. Resident
+   * pages are evicted and any older in-flight fetch is cleared when it settles.
+   * The next miss establishes the new bounded window.
+   */
+  resetSource(clipId: number): void {
+    const state = this.sources.get(clipId);
+    if (state) {
+      this.resetState(state);
+    }
+  }
+
   /**
    * Drain pending page-miss requests, fetch the missing pages plus their
    * read-ahead window, and evict out-of-window pages. Resolves once this round's
@@ -113,9 +139,10 @@ export class ClipPageStreamer {
     if (this.closed) {
       return;
     }
-    // Collapse this round's misses to the furthest-advanced frontier per clip:
-    // multiple channels of one clip miss the same page, and a run of misses
-    // walks forward, so only the latest position needs servicing.
+    // Collapse this round's misses to the latest observed frontier per clip.
+    // Queue order reflects playback order, so a backward seek/loop request that
+    // follows a stale high-page miss must win even though its page index is
+    // smaller. Multiple channel misses still collapse to one service window.
     const frontiers = new Map<number, number>();
     for (let drained = 0; drained < this.maxRequestsPerPump; ++drained) {
       const request = this.engine.popClipPageRequest();
@@ -127,10 +154,7 @@ export class ClipPageStreamer {
         continue;
       }
       const page = Math.floor(request.sample / state.source.pageFrames);
-      const previous = frontiers.get(request.clipId);
-      if (previous === undefined || page > previous) {
-        frontiers.set(request.clipId, page);
-      }
+      frontiers.set(request.clipId, page);
     }
 
     const fetches: Promise<unknown>[] = [];
@@ -151,18 +175,27 @@ export class ClipPageStreamer {
     }
     this.closed = true;
     for (const state of this.sources.values()) {
+      this.resetState(state);
       state.source.binding.close();
     }
     this.sources.clear();
   }
 
   private serviceFrontier(state: SourceState, frontier: number): Promise<unknown>[] {
+    // A lower frontier after a previously serviced high page is a seek/loop
+    // discontinuity. Advance generation before scheduling its new window so an
+    // older asynchronous fetch can never become resident in the new window.
+    if (state.lastFrontier !== null && frontier < state.lastFrontier) {
+      this.resetState(state);
+    }
+    state.lastFrontier = frontier;
+    const generation = state.generation;
     const low = Math.max(0, frontier - this.retainBehindPages);
     const high = Math.min(state.lastPage, frontier + this.readAheadPages);
 
     // Evict pages outside the window first so a burst of fetches never exceeds
     // the bound by transiently holding old pages alongside new ones.
-    for (const page of state.resident) {
+    for (const page of state.resident.keys()) {
       if (page < low || page > high) {
         state.source.binding.provider.clear(page);
         state.resident.delete(page);
@@ -171,23 +204,29 @@ export class ClipPageStreamer {
 
     const fetches: Promise<unknown>[] = [];
     for (let page = low; page <= high; ++page) {
-      if (state.resident.has(page)) {
+      if (state.resident.get(page) === generation) {
         continue;
       }
       // Mark resident eagerly so the same page is not fetched twice across
       // overlapping windows; drop it again if the fetch reports a miss.
-      state.resident.add(page);
+      state.resident.set(page, generation);
       const pageIndex = page;
       fetches.push(
         state.source.binding.supplyPage(pageIndex).then(
           (ok) => {
-            if (!ok) {
+            if (state.generation !== generation) {
+              // The fetch crossed a seek/reset boundary. supplyPage may have
+              // installed it after resetState's clear pass, so clear it again.
+              state.source.binding.provider.clear(pageIndex);
+            } else if (!ok && state.resident.get(pageIndex) === generation) {
               state.resident.delete(pageIndex);
             }
             return ok;
           },
           (error) => {
-            state.resident.delete(pageIndex);
+            if (state.resident.get(pageIndex) === generation) {
+              state.resident.delete(pageIndex);
+            }
             throw error;
           },
         ),
@@ -195,6 +234,15 @@ export class ClipPageStreamer {
     }
     return fetches;
   }
+
+  private resetState(state: SourceState): void {
+    state.generation += 1;
+    state.lastFrontier = null;
+    for (const page of state.resident.keys()) {
+      state.source.binding.provider.clear(page);
+    }
+    state.resident.clear();
+  }
 }
 
 export interface OpfsClipStreamOptions extends OpfsClipPageProviderOptions {

package/src/effects_voice_change.ts

@@ -40,9 +40,6 @@ export function voiceChange(
 
 /** 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). */
@@ -90,10 +87,16 @@ function latencyCompensatedVoiceChange(
  * and Node `voiceChangeRealtime` convenience wrappers. For mono, `samples` is a
  * plain mono buffer; for stereo, `samples` 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)
+ * @param preset - Voice-changer preset id or full config object
+ * @param options - Channel count and block size ({@link VoiceChangeRealtimeOptions})
  * @returns The processed buffer (same layout/length as the input).
  */
 export function voiceChangeRealtime(
   samples: Float32Array,
+  sampleRate = 48000,
+  preset: RealtimeVoiceChangerConfigInput = 'neutral-monitor',
   options: VoiceChangeRealtimeOptions = {},
 ): Float32Array {
   assertSamples('voiceChangeRealtime', samples, options.validate !== false);
@@ -104,11 +107,8 @@ export function voiceChangeRealtime(
   if (channels === 2 && samples.length % 2 !== 0) {
     throw new Error('voiceChangeRealtime: stereo input length must be a multiple of 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');
+  const changer = new RealtimeVoiceChanger(preset);
   try {
     changer.prepare(sampleRate, blockSize, channels);
     return latencyCompensatedVoiceChange(changer, samples, channels, blockSize);

package/src/feature_music.ts

@@ -366,19 +366,22 @@ export function fourierTempogram(
  * @param winLength - Window length in frames (default: 384)
  * @param sampleRate - Sample rate in Hz (default: 22050)
  * @param hopLength - Hop length (default: 512)
- * @returns Tempogram ratio features
+ * @param factors - Lag ratios to evaluate. When omitted or empty, the library
+ *   default {0.5, 1, 2, 3, 4} is used.
+ * @returns Tempogram ratio features (one value per factor)
  */
 export function tempogramRatio(
   tempogramData: Float32Array,
   winLength = 384,
   sampleRate = 22050,
   hopLength = 512,
+  factors?: Float32Array | number[],
   options: GuardedOptions = {},
 ): Float32Array {
   assertSampleRate('tempogramRatio', sampleRate);
   assertSamples('tempogramRatio', tempogramData, options.validate !== false, 'tempogramData');
   validatePositiveIntegers('tempogramRatio', { winLength, hopLength });
-  return requireModule().tempogramRatio(tempogramData, winLength, sampleRate, hopLength);
+  return requireModule().tempogramRatio(tempogramData, winLength, sampleRate, hopLength, factors);
 }
 
 /**

package/src/index.ts

@@ -561,6 +561,18 @@ export function version(): string {
   return module.version();
 }
 
+/**
+ * Aggregate native ABI version: the per-subsystem ABI macros folded into one
+ * 32-bit value. It bumps whenever any flat C POD layout changes, so callers can
+ * detect an incompatible prebuilt binary. Matches the Node/Python `abiVersion()`.
+ */
+export function abiVersion(): number {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  return module.abiVersion();
+}
+
 export function engineAbiVersion(): number {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');

package/src/mixer.ts

@@ -522,6 +522,14 @@ export class Mixer {
     return this.mixer.tailSamples();
   }
 
+  /**
+   * Reported latency (samples) of the compiled mixer graph, for aligning
+   * dry/wet material. Lazily compiles the routing graph if the topology is dirty.
+   */
+  latencySamples(): number {
+    return this.mixer.latencySamples();
+  }
+
   /**
    * Drain delayed / tail audio by processing a zero-input block of `numSamples`
    * frames after the host stops feeding strip inputs. Returns the mixed stereo

package/src/project_class.ts

@@ -542,8 +542,10 @@ export class Project {
    * built-in oscillator synth so a MIDI-only arrangement bounces to audible
    * audio. Pass a {@link BuiltinSynthBinding} (or an array of them) to choose
    * the patch and MIDI destination; omit it (or pass `{}`) for one
-   * default-destination sine patch. An explicitly empty array `[]` (or
-   * `undefined` / `null`) produces zero bindings, so MIDI tracks render silently.
+   * default-destination sine patch. Because the parameter defaults to `{}`,
+   * omission and explicit `undefined` both create that one default binding.
+   * Use an explicitly empty array `[]` (or runtime `null`) for zero bindings,
+   * so MIDI tracks render silently.
    *
    * Like {@link bounce}, omitting `totalFrames` auto-derives the render length
    * from the arrangement plus the synth's release tail.
@@ -572,9 +574,10 @@ export class Project {
    * string (`'saw-lead'` / `'va:saw-lead'`; see {@link synthPresetNames}), or
    * an array of either; each object entry may carry a `destinationId` binding
    * convenience (default 0), which is not part of the NativeSynth patch itself.
-   * An explicitly empty array (or `undefined` / `null`) produces zero bindings.
-   * Unknown preset names throw. Deterministic for a fixed project + options +
-   * patch.
+   * Because the parameter defaults to `{}`, omission and explicit `undefined`
+   * both create one default binding. Use an explicitly empty array `[]` (or
+   * runtime `null`) for zero bindings. Unknown preset names throw.
+   * Deterministic for a fixed project + options + patch.
    */
   bounceWithSynthInstrument(
     instrument: SynthPatch | string | ReadonlyArray<SynthPatch | string> = {},
@@ -624,8 +627,10 @@ export class Project {
    * honored. Programs the SoundFont does not cover — including bouncing with
    * no SoundFont loaded at all — play through the built-in synthesizer GM
    * fallback bank (the data-free floor; see {@link soundFontManifest} for the
-   * per-program backend). An explicitly empty array `[]` (or `undefined` /
-   * `null`) produces zero bindings, so MIDI tracks render silently.
+   * per-program backend). Because the parameter defaults to `{}`, omission and
+   * explicit `undefined` both create one default binding. Use an explicitly
+   * empty array `[]` (or runtime `null`) for zero bindings, so MIDI tracks
+   * render silently.
    */
   bounceWithSf2Instrument(
     instrument: Sf2InstrumentConfig | ReadonlyArray<Sf2InstrumentConfig> = {},
@@ -815,6 +820,11 @@ export class Project {
     return this.native.trackCount();
   }
 
+  /** Number of clips in the project. */
+  clipCount(): number {
+    return this.native.clipCount();
+  }
+
   /** Number of audio sources registered on the project. */
   sourceCount(): number {
     return this.native.sourceCount();

package/src/project_internal.ts

@@ -146,6 +146,7 @@ export interface WasmProject {
   markerByIndex: (index: number) => ProjectMarker;
   markerCount: () => number;
   trackCount: () => number;
+  clipCount: () => number;
   sourceCount: () => number;
   tempoSegmentCount: () => number;
   timeSignatureCount: () => number;

package/src/public_types_realtime.ts

@@ -117,47 +117,47 @@ export interface RealtimeVoiceChangerPreset {
 export type RealtimeVoiceChangerConfigInput = VoicePresetId | RealtimeVoiceChangerPreset;
 
 /**
- * Flat (POD) realtime voice-changer configuration. Field names mirror the
- * C ABI `SonareRealtimeVoiceChangerConfig` / Python POD exactly (snake_case),
- * so a config can be round-tripped across bindings without renaming.
+ * Flat (POD) realtime voice-changer configuration. Keys are camelCase to match
+ * the Node addon getter, so a preset config reads identically across both JS
+ * surfaces (the underlying C ABI / Python POD uses the snake_case equivalents).
  */
 export interface RealtimeVoiceChangerPodConfig {
-  input_gain_db: number;
-  output_gain_db: number;
-  wet_mix: number;
-  retune_semitones: number;
-  retune_mix: number;
-  retune_grain_size: number;
-  formant_factor: number;
-  formant_amount: number;
-  formant_body: number;
-  formant_brightness: number;
-  formant_nasal: number;
-  eq_highpass_hz: number;
-  eq_body_db: number;
-  eq_presence_db: number;
-  eq_air_db: number;
-  gate_threshold_db: number;
-  gate_attack_ms: number;
-  gate_release_ms: number;
-  gate_range_db: number;
-  compressor_threshold_db: number;
-  compressor_ratio: number;
-  compressor_attack_ms: number;
-  compressor_release_ms: number;
-  compressor_makeup_gain_db: number;
-  deesser_frequency_hz: number;
-  deesser_threshold_db: number;
-  deesser_ratio: number;
-  deesser_range_db: number;
-  reverb_mix: number;
-  reverb_time_ms: number;
-  reverb_damping: number;
-  reverb_seed: number;
-  limiter_ceiling_db: number;
-  limiter_release_ms: number;
+  inputGainDb: number;
+  outputGainDb: number;
+  wetMix: number;
+  retuneSemitones: number;
+  retuneMix: number;
+  retuneGrainSize: number;
+  formantFactor: number;
+  formantAmount: number;
+  formantBody: number;
+  formantBrightness: number;
+  formantNasal: number;
+  eqHighpassHz: number;
+  eqBodyDb: number;
+  eqPresenceDb: number;
+  eqAirDb: number;
+  gateThresholdDb: number;
+  gateAttackMs: number;
+  gateReleaseMs: number;
+  gateRangeDb: number;
+  compressorThresholdDb: number;
+  compressorRatio: number;
+  compressorAttackMs: number;
+  compressorReleaseMs: number;
+  compressorMakeupGainDb: number;
+  deesserFrequencyHz: number;
+  deesserThresholdDb: number;
+  deesserRatio: number;
+  deesserRangeDb: number;
+  reverbMix: number;
+  reverbTimeMs: number;
+  reverbDamping: number;
+  reverbSeed: number;
+  limiterCeilingDb: number;
+  limiterReleaseMs: number;
   /** Non-zero enables the 4x-oversampled inter-sample-peak limiter (default enabled). */
-  limiter_enable_isp_limiter: boolean;
+  limiterEnableIspLimiter: boolean;
   /** True-peak ceiling in dBTP applied by the ISP limiter (default -1.0). */
-  limiter_isp_ceiling_dbtp: number;
+  limiterIspCeilingDbtp: number;
 }

package/src/sonare.js.d.ts

@@ -26,45 +26,45 @@ export interface WasmKeyCandidateResult {
   correlation: number;
 }
 
-// Flat POD mirror of SonareRealtimeVoiceChangerConfig. Field names match the
-// C ABI / Python POD exactly (snake_case).
+// Flat POD mirror of SonareRealtimeVoiceChangerConfig. Keys are camelCase to
+// match the Node addon getter (the underlying C ABI / Python POD is snake_case).
 export interface WasmRealtimeVoiceChangerPodConfig {
-  input_gain_db: number;
-  output_gain_db: number;
-  wet_mix: number;
-  retune_semitones: number;
-  retune_mix: number;
-  retune_grain_size: number;
-  formant_factor: number;
-  formant_amount: number;
-  formant_body: number;
-  formant_brightness: number;
-  formant_nasal: number;
-  eq_highpass_hz: number;
-  eq_body_db: number;
-  eq_presence_db: number;
-  eq_air_db: number;
-  gate_threshold_db: number;
-  gate_attack_ms: number;
-  gate_release_ms: number;
-  gate_range_db: number;
-  compressor_threshold_db: number;
-  compressor_ratio: number;
-  compressor_attack_ms: number;
-  compressor_release_ms: number;
-  compressor_makeup_gain_db: number;
-  deesser_frequency_hz: number;
-  deesser_threshold_db: number;
-  deesser_ratio: number;
-  deesser_range_db: number;
-  reverb_mix: number;
-  reverb_time_ms: number;
-  reverb_damping: number;
-  reverb_seed: number;
-  limiter_ceiling_db: number;
-  limiter_release_ms: number;
-  limiter_enable_isp_limiter: boolean;
-  limiter_isp_ceiling_dbtp: number;
+  inputGainDb: number;
+  outputGainDb: number;
+  wetMix: number;
+  retuneSemitones: number;
+  retuneMix: number;
+  retuneGrainSize: number;
+  formantFactor: number;
+  formantAmount: number;
+  formantBody: number;
+  formantBrightness: number;
+  formantNasal: number;
+  eqHighpassHz: number;
+  eqBodyDb: number;
+  eqPresenceDb: number;
+  eqAirDb: number;
+  gateThresholdDb: number;
+  gateAttackMs: number;
+  gateReleaseMs: number;
+  gateRangeDb: number;
+  compressorThresholdDb: number;
+  compressorRatio: number;
+  compressorAttackMs: number;
+  compressorReleaseMs: number;
+  compressorMakeupGainDb: number;
+  deesserFrequencyHz: number;
+  deesserThresholdDb: number;
+  deesserRatio: number;
+  deesserRangeDb: number;
+  reverbMix: number;
+  reverbTimeMs: number;
+  reverbDamping: number;
+  reverbSeed: number;
+  limiterCeilingDb: number;
+  limiterReleaseMs: number;
+  limiterEnableIspLimiter: boolean;
+  limiterIspCeilingDbtp: number;
 }
 
 export interface WasmBeatResult {
@@ -194,6 +194,7 @@ export interface WasmStreamConfigDefaults {
   computeSpectral: boolean;
   emitEveryNFrames: number;
   magnitudeDownsample: number;
+  maxPendingFrames: number;
   keyUpdateIntervalSec: number;
   bpmUpdateIntervalSec: number;
   window: number;
@@ -1156,6 +1157,7 @@ export interface SonareModule {
   detectKeyCandidates: (samples: Float32Array, sampleRate: number) => WasmKeyCandidateResult[];
   hasFfmpegSupport: () => boolean;
   version: () => string;
+  abiVersion: () => number;
   engineAbiVersion: () => number;
   voiceChangerAbiVersion: () => number;
   voiceCharacterPresetId: (preset: number) => string | null;
@@ -1948,6 +1950,7 @@ export interface SonareModule {
     winLength: number,
     sampleRate: number,
     hopLength: number,
+    factors?: Float32Array | number[],
   ) => Float32Array;
   lufs: (samples: Float32Array, sampleRate: number) => WasmLufsResult;
   momentaryLufs: (samples: Float32Array, sampleRate: number) => Float32Array;
@@ -2024,6 +2027,7 @@ export interface SonareModule {
     computeSpectral: boolean,
     emitEveryNFrames: number,
     magnitudeDownsample: number,
+    maxPendingFrames: number,
     keyUpdateIntervalSec: number,
     bpmUpdateIntervalSec: number,
     window: number,
@@ -2234,6 +2238,7 @@ export interface WasmMixer {
   vcaGroupCount: () => number;
   toSceneJson: () => string;
   tailSamples: () => number;
+  latencySamples: () => number;
   drainTailStereo: (numSamples: number) => {
     left: Float32Array;
     right: Float32Array;
@@ -2297,6 +2302,8 @@ export interface WasmAnalyzerStats {
   totalFrames: number;
   totalSamples: number;
   durationSeconds: number;
+  pendingFrames: number;
+  droppedOutputFrames: number;
   estimate: WasmProgressiveEstimate;
 }
 

package/src/stream_analyzer.ts

@@ -71,6 +71,7 @@ export class StreamAnalyzer {
       config.computeSpectral ?? defaults.computeSpectral,
       config.emitEveryNFrames ?? defaults.emitEveryNFrames,
       config.magnitudeDownsample ?? defaults.magnitudeDownsample,
+      config.maxPendingFrames ?? defaults.maxPendingFrames,
       config.keyUpdateIntervalSec ?? defaults.keyUpdateIntervalSec,
       config.bpmUpdateIntervalSec ?? defaults.bpmUpdateIntervalSec,
       config.window ?? defaults.window,
@@ -163,6 +164,8 @@ export class StreamAnalyzer {
       totalFrames: s.totalFrames,
       totalSamples: s.totalSamples,
       durationSeconds: s.durationSeconds,
+      pendingFrames: s.pendingFrames,
+      droppedOutputFrames: s.droppedOutputFrames,
       estimate: {
         bpm: s.estimate.bpm,
         bpmConfidence: s.estimate.bpmConfidence,

package/src/stream_types.ts

@@ -64,6 +64,8 @@ export interface AnalyzerStats {
   totalFrames: number;
   totalSamples: number;
   durationSeconds: number;
+  pendingFrames: number;
+  droppedOutputFrames: number;
   estimate: ProgressiveEstimate;
 }
 
@@ -159,6 +161,8 @@ export interface StreamConfig {
   computeSpectral?: boolean;
   emitEveryNFrames?: number;
   magnitudeDownsample?: number;
+  /** Maximum unread frames; overflow drops the oldest frame. */
+  maxPendingFrames?: number;
   keyUpdateIntervalSec?: number;
   bpmUpdateIntervalSec?: number;
   window?: number;