@libraz/libsonare 1.5.1 → 1.5.2

package/package.json

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

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/...).
  *

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';

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,7 +515,7 @@ 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 {

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/sonare.js.d.ts

@@ -195,6 +195,7 @@ export interface WasmStreamConfigDefaults {
   emitEveryNFrames: number;
   magnitudeDownsample: number;
   maxPendingFrames: number;
+  maxProgressionEntries: number;
   keyUpdateIntervalSec: number;
   bpmUpdateIntervalSec: number;
   window: number;
@@ -1906,6 +1907,27 @@ export interface SonareModule {
     binsPerOctave: number,
     gamma: number,
   ) => WasmCqtResult;
+  cqtToAudio: (
+    magnitude: Float32Array,
+    nBins: number,
+    nFrames: number,
+    sampleRate: number,
+    hopLength: number,
+    fmin: number,
+    binsPerOctave: number,
+    nIter: number,
+  ) => Float32Array;
+  vqtToAudio: (
+    magnitude: Float32Array,
+    nBins: number,
+    nFrames: number,
+    sampleRate: number,
+    hopLength: number,
+    fmin: number,
+    binsPerOctave: number,
+    gamma: number,
+    nIter: number,
+  ) => Float32Array;
   analyzeSections: (
     samples: Float32Array,
     sampleRate: number,
@@ -2028,6 +2050,7 @@ export interface SonareModule {
     emitEveryNFrames: number,
     magnitudeDownsample: number,
     maxPendingFrames: number,
+    maxProgressionEntries: number,
     keyUpdateIntervalSec: number,
     bpmUpdateIntervalSec: number,
     window: number,
@@ -2304,6 +2327,8 @@ export interface WasmAnalyzerStats {
   durationSeconds: number;
   pendingFrames: number;
   droppedOutputFrames: number;
+  droppedChordProgressionEntries: number;
+  droppedBarProgressionEntries: number;
   estimate: WasmProgressiveEstimate;
 }
 

package/src/stream_analyzer.ts

@@ -72,6 +72,7 @@ export class StreamAnalyzer {
       config.emitEveryNFrames ?? defaults.emitEveryNFrames,
       config.magnitudeDownsample ?? defaults.magnitudeDownsample,
       config.maxPendingFrames ?? defaults.maxPendingFrames,
+      config.maxProgressionEntries ?? defaults.maxProgressionEntries,
       config.keyUpdateIntervalSec ?? defaults.keyUpdateIntervalSec,
       config.bpmUpdateIntervalSec ?? defaults.bpmUpdateIntervalSec,
       config.window ?? defaults.window,
@@ -89,7 +90,8 @@ export class StreamAnalyzer {
   }
 
   /**
-   * Process audio samples with explicit sample offset.
+   * Process audio samples with a contiguous explicit sample offset. A gap,
+   * seek, or switch from `process()` requires `reset()` first.
    *
    * @param samples - Audio samples (mono, float32)
    * @param sampleOffset - Cumulative sample count at start of this chunk
@@ -166,6 +168,8 @@ export class StreamAnalyzer {
       durationSeconds: s.durationSeconds,
       pendingFrames: s.pendingFrames,
       droppedOutputFrames: s.droppedOutputFrames,
+      droppedChordProgressionEntries: s.droppedChordProgressionEntries,
+      droppedBarProgressionEntries: s.droppedBarProgressionEntries,
       estimate: {
         bpm: s.estimate.bpm,
         bpmConfidence: s.estimate.bpmConfidence,

package/src/stream_types.ts

@@ -66,6 +66,8 @@ export interface AnalyzerStats {
   durationSeconds: number;
   pendingFrames: number;
   droppedOutputFrames: number;
+  droppedChordProgressionEntries: number;
+  droppedBarProgressionEntries: number;
   estimate: ProgressiveEstimate;
 }
 
@@ -163,6 +165,8 @@ export interface StreamConfig {
   magnitudeDownsample?: number;
   /** Maximum unread frames; overflow drops the oldest frame. */
   maxPendingFrames?: number;
+  /** Maximum retained chord and bar progression entries; overflow drops oldest. */
+  maxProgressionEntries?: number;
   keyUpdateIntervalSec?: number;
   bpmUpdateIntervalSec?: number;
   window?: number;