@libraz/libsonare 1.5.0 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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

@@ -180,6 +180,111 @@ export function vqt(
   return requireModule().vqt(samples, sampleRate, hopLength, fmin, nBins, binsPerOctave, gamma);
 }
 
+function validateCqtInverse(
+  fnName: string,
+  magnitude: Float32Array,
+  nBins: number,
+  nFrames: number,
+  sampleRate: number,
+  hopLength: number,
+  fmin: number,
+  binsPerOctave: number,
+  nIter: number,
+  options: GuardedOptions,
+): void {
+  assertSampleRate(fnName, sampleRate);
+  validatePositiveIntegers(fnName, { nBins, nFrames, hopLength, binsPerOctave, nIter });
+  if (nIter > 256) {
+    throw new RangeError(`${fnName}: nIter must be at most 256`);
+  }
+  validateFrequencyBounds(fnName, fmin);
+  if (fmin === 0) {
+    throw new RangeError(`${fnName}: fmin must be positive`);
+  }
+  if (magnitude.length !== nBins * nFrames) {
+    throw new RangeError(`${fnName}: magnitude length must equal nBins * nFrames`);
+  }
+  assertSamples(fnName, magnitude, options.validate !== false);
+}
+
+/** Reconstruct mono audio from row-major CQT magnitude via Griffin-Lim. */
+export function cqtToAudio(
+  magnitude: Float32Array,
+  nBins: number,
+  nFrames: number,
+  sampleRate = 22050,
+  hopLength = 512,
+  fmin = 32.70319566257483,
+  binsPerOctave = 12,
+  nIter = 32,
+  options: GuardedOptions = {},
+): Float32Array {
+  validateCqtInverse(
+    'cqtToAudio',
+    magnitude,
+    nBins,
+    nFrames,
+    sampleRate,
+    hopLength,
+    fmin,
+    binsPerOctave,
+    nIter,
+    options,
+  );
+  return requireModule().cqtToAudio(
+    magnitude,
+    nBins,
+    nFrames,
+    sampleRate,
+    hopLength,
+    fmin,
+    binsPerOctave,
+    nIter,
+  );
+}
+
+/** Reconstruct mono audio from row-major VQT magnitude via Griffin-Lim. */
+export function vqtToAudio(
+  magnitude: Float32Array,
+  nBins: number,
+  nFrames: number,
+  sampleRate = 22050,
+  hopLength = 512,
+  fmin = 32.70319566257483,
+  binsPerOctave = 12,
+  gamma = 0,
+  nIter = 32,
+  options: GuardedOptions = {},
+): Float32Array {
+  validateCqtInverse(
+    'vqtToAudio',
+    magnitude,
+    nBins,
+    nFrames,
+    sampleRate,
+    hopLength,
+    fmin,
+    binsPerOctave,
+    nIter,
+    options,
+  );
+  assertFiniteScalar('vqtToAudio', gamma, 'gamma');
+  if (gamma < 0) {
+    throw new RangeError('vqtToAudio: gamma must be non-negative');
+  }
+  return requireModule().vqtToAudio(
+    magnitude,
+    nBins,
+    nFrames,
+    sampleRate,
+    hopLength,
+    fmin,
+    binsPerOctave,
+    gamma,
+    nIter,
+  );
+}
+
 /**
  * Detect song-structure sections (intro/verse/chorus/...).
  *
@@ -366,19 +471,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/features.ts

@@ -33,6 +33,7 @@ export {
   analyzeMelody,
   analyzeSections,
   cqt,
+  cqtToAudio,
   fourierTempogram,
   hybridCqt,
   lufs,
@@ -44,6 +45,7 @@ export {
   shortTermLufs,
   tempogramRatio,
   vqt,
+  vqtToAudio,
 } from './feature_music';
 export { pitchPyin, pitchYin } from './feature_pitch';
 export { resample } from './feature_resample';

package/src/index.ts

@@ -125,6 +125,7 @@ export {
   chromaCens,
   chromaCqt,
   cqt,
+  cqtToAudio,
   cyclicTempogram,
   dbToAmplitude,
   dbToPower,
@@ -193,6 +194,7 @@ export {
   trimSilence,
   vectorNormalize,
   vqt,
+  vqtToAudio,
   zeroCrossingRate,
   zeroCrossings,
 } from './features';
@@ -445,6 +447,7 @@ export type {
   EngineTrackLane,
   EngineTrackSend,
   EngineTransportState,
+  ExternalMidiEvent,
   MidiCcBindOptions,
 } from './realtime_engine';
 export { EXPECTED_ENGINE_ABI_VERSION, engineCapabilities, RealtimeEngine } from './realtime_engine';
@@ -561,6 +564,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/mastering_core.ts

@@ -129,6 +129,16 @@ export interface MasteringProcessorCatalogEntry {
   realtimeInsertable: boolean;
   /** True for processors with no mono implementation (stereo-only). */
   stereoOnly: boolean;
+  /**
+   * Reported latency for the default 48 kHz / 512-sample probe configuration.
+   * Zero for offline processors; configuration-dependent values are estimates.
+   */
+  latencySamples: number;
+  /**
+   * Audible decay length for the same default prepared probe. Zero for
+   * offline, dry-only, and no-tail processors.
+   */
+  tailSamples: number;
   /**
    * How the mixer wraps the processor on a >2-channel (surround) bus insert:
    * "multichannel" (one full-buffer call) or "stereoPairOnly" (front L/R pair,

package/src/mixer.ts

@@ -515,13 +515,21 @@ export class Mixer {
   }
 
   /**
-   * Maximum processor tail length (samples) in the compiled mixer graph. Lazily
+   * Longest audible serial processor-tail path to the master, in samples. Lazily
    * compiles the routing graph if the topology is dirty.
    */
   tailSamples(): number {
     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_music.ts

@@ -140,6 +140,7 @@ export interface KeyCandidate {
 export interface ChordDetectionOptions extends ValidateOptions {
   minDuration?: number;
   smoothingWindow?: number;
+  /** Final-template correlation threshold in [0, 1]; below it emits Unknown / N.C. */
   threshold?: number;
   useTriadsOnly?: boolean;
   nFft?: 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;
 }