@libraz/libsonare 1.5.5 → 1.7.0

package/src/feature_spectral.ts

@@ -1,4 +1,5 @@
 import { getSonareModule } from './module_state';
+import type { SegmentMatrix } from './public_types';
 import type {
   WasmDecomposeResult,
   WasmHpssWithResidualResult,
@@ -6,12 +7,53 @@ import type {
   WasmMatrix2dResult,
 } from './sonare.js';
 import type { ValidateOptions } from './validation';
-import { assertInterleavedSamples, assertSampleRate } from './validation';
+import {
+  assertInterleavedSamples,
+  assertNonNegativeInteger,
+  assertPositiveInteger,
+  assertSampleRate,
+  assertSamples,
+} from './validation';
 
 function requireModule() {
   return getSonareModule();
 }
 
+function resolveEffectFftOptions(
+  fnName: string,
+  nFft: unknown,
+  hopLength: unknown,
+): { nFft: number; hopLength: number } {
+  const resolvedNFft = nFft === undefined ? 2048 : nFft;
+  const resolvedHopLength = hopLength === undefined ? 512 : hopLength;
+  if (typeof resolvedNFft !== 'number' || !Number.isInteger(resolvedNFft)) {
+    throw new TypeError(`${fnName}: nFft must be an integer`);
+  }
+  if (resolvedNFft < 2 || resolvedNFft > 2 ** 30) {
+    throw new RangeError(`${fnName}: nFft must be an even power of two >= 2`);
+  }
+  if ((resolvedNFft & (resolvedNFft - 1)) !== 0) {
+    throw new RangeError(`${fnName}: nFft must be an even power of two >= 2`);
+  }
+  if (typeof resolvedHopLength !== 'number' || !Number.isInteger(resolvedHopLength)) {
+    throw new TypeError(`${fnName}: hopLength must be an integer`);
+  }
+  if (resolvedHopLength <= 0 || resolvedHopLength > 2 ** 31 - 1) {
+    throw new RangeError(`${fnName}: hopLength must be a positive integer`);
+  }
+  return { nFft: resolvedNFft, hopLength: resolvedHopLength };
+}
+
+function resolveHardMask(fnName: string, value: unknown): boolean {
+  if (value === undefined) {
+    return false;
+  }
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`${fnName}: hardMask must be a boolean`);
+  }
+  return value;
+}
+
 /** Canonical request form for frame-based spectral feature extraction. */
 export interface SpectralFrameRequest {
   samples: Float32Array;
@@ -76,6 +118,75 @@ export interface NnFilterRequest {
   k?: number;
   width?: number;
 }
+export interface SegmentCrossSimilarityRequest {
+  x: Float32Array;
+  xRows: number;
+  xCols: number;
+  y: Float32Array;
+  yRows: number;
+  yCols: number;
+  k?: number;
+  metric?: 'cosine' | 'euclidean';
+  mode?: 'connectivity' | 'affinity';
+}
+export interface SegmentRecurrenceMatrixRequest {
+  data: Float32Array;
+  rows: number;
+  cols: number;
+  k?: number;
+  width?: number;
+  sym?: boolean;
+  metric?: 'cosine' | 'euclidean';
+  mode?: 'connectivity' | 'affinity';
+}
+export interface SegmentRecurrenceToLagRequest {
+  recurrence: Float32Array;
+  n: number;
+  pad?: boolean;
+}
+export interface SegmentLagToRecurrenceRequest {
+  lag: Float32Array;
+  rows: number;
+  lags: number;
+}
+export interface SegmentSubsegmentRequest {
+  data: Float32Array;
+  rows: number;
+  cols: number;
+  boundaries: Int32Array;
+  nSegments?: number;
+}
+export interface SegmentAgglomerativeRequest {
+  data: Float32Array;
+  rows: number;
+  cols: number;
+  k: number;
+  linkage?: 'average' | 'single' | 'complete' | 'ward';
+}
+export interface SegmentPathEnhanceRequest {
+  recurrence: Float32Array;
+  n: number;
+  win: number;
+  maxRatio?: number;
+  minRatio?: number;
+  nFilters?: number;
+}
+
+function validateSegmentMatrix(
+  fnName: string,
+  data: Float32Array,
+  rows: number,
+  cols: number,
+  dataName: string,
+): void {
+  assertPositiveInteger(fnName, rows, 'rows');
+  assertPositiveInteger(fnName, cols, 'cols');
+  assertSamples(fnName, data, true, dataName);
+  const expected = rows * cols;
+  if (!Number.isSafeInteger(expected) || data.length !== expected) {
+    throw new RangeError(`${fnName}: ${dataName} length must equal rows * cols`);
+  }
+}
 export interface RemixRequest {
   samples: Float32Array;
   intervals: Int32Array | ArrayLike<number>;
@@ -90,6 +201,9 @@ export interface HpssWithResidualRequest {
   sampleRate?: number;
   kernelHarmonic?: number;
   kernelPercussive?: number;
+  nFft?: number;
+  hopLength?: number;
+  hardMask?: boolean;
 }
 export interface LufsInterleavedRequest extends ValidateOptions {
   samples: Float32Array;
@@ -466,18 +580,42 @@ export function hpssWithResidual(
   sampleRate?: number,
   kernelHarmonic?: number,
   kernelPercussive?: number,
+  nFft?: number,
+  hopLength?: number,
+  hardMask?: boolean,
 ): WasmHpssWithResidualResult;
 export function hpssWithResidual(
   samples: Float32Array | HpssWithResidualRequest,
   sampleRate = 22050,
   kernelHarmonic = 31,
   kernelPercussive = 31,
+  nFft?: number,
+  hopLength?: number,
+  hardMask?: boolean,
 ): WasmHpssWithResidualResult {
   if (!(samples instanceof Float32Array)) {
     const r = samples;
-    return hpssWithResidual(r.samples, r.sampleRate, r.kernelHarmonic, r.kernelPercussive);
+    return hpssWithResidual(
+      r.samples,
+      r.sampleRate,
+      r.kernelHarmonic,
+      r.kernelPercussive,
+      r.nFft,
+      r.hopLength,
+      r.hardMask,
+    );
   }
-  return requireModule().hpssWithResidual(samples, sampleRate, kernelHarmonic, kernelPercussive);
+  const fftOptions = resolveEffectFftOptions('hpssWithResidual', nFft, hopLength);
+  const resolvedHardMask = resolveHardMask('hpssWithResidual', hardMask);
+  return requireModule().hpssWithResidualEx(
+    samples,
+    sampleRate,
+    kernelHarmonic,
+    kernelPercussive,
+    fftOptions.nFft,
+    fftOptions.hopLength,
+    resolvedHardMask,
+  );
 }
 
 /**
@@ -537,23 +675,31 @@ export function ebur128LoudnessRange(
  * @param hopLength - Hop length (default: 512)
  * @returns Spectral bandwidth in Hz for each frame
  */
-export function spectralBandwidth(request: SpectralFrameRequest): Float32Array;
+export function spectralBandwidth(request: SpectralFrameRequest & { p?: number }): Float32Array;
 export function spectralBandwidth(
   samples: Float32Array,
   sampleRate?: number,
   nFft?: number,
   hopLength?: number,
+  p?: number,
 ): Float32Array;
 export function spectralBandwidth(
-  samples: Float32Array | SpectralFrameRequest,
+  samples: Float32Array | (SpectralFrameRequest & { p?: number }),
   sampleRate = 22050,
   nFft = 2048,
   hopLength = 512,
+  p = 2,
 ): Float32Array {
   if (!(samples instanceof Float32Array)) {
-    return spectralBandwidth(samples.samples, samples.sampleRate, samples.nFft, samples.hopLength);
+    return spectralBandwidth(
+      samples.samples,
+      samples.sampleRate,
+      samples.nFft,
+      samples.hopLength,
+      samples.p,
+    );
   }
-  return requireModule().spectralBandwidth(samples, sampleRate, nFft, hopLength);
+  return requireModule().spectralBandwidth(samples, sampleRate, nFft, hopLength, p);
 }
 
 /**
@@ -621,6 +767,33 @@ export function spectralFlatness(
   return requireModule().spectralFlatness(samples, sampleRate, nFft, hopLength);
 }
 
+export function spectralFlux(request: SpectralFrameRequest & { lag?: number }): Float32Array;
+export function spectralFlux(
+  samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  lag?: number,
+): Float32Array;
+export function spectralFlux(
+  samples: Float32Array | (SpectralFrameRequest & { lag?: number }),
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  lag = 1,
+): Float32Array {
+  if (!(samples instanceof Float32Array)) {
+    return spectralFlux(
+      samples.samples,
+      samples.sampleRate,
+      samples.nFft,
+      samples.hopLength,
+      samples.lag,
+    );
+  }
+  return requireModule().spectralFlux(samples, sampleRate, nFft, hopLength, lag);
+}
+
 /**
  * Compute zero crossing rate.
  *
@@ -681,3 +854,118 @@ export function rmsEnergy(
   }
   return requireModule().rmsEnergy(samples, sampleRate, frameLength, hopLength);
 }
+
+/** Column-wise cross-similarity (librosa.segment.cross_similarity). */
+export function segmentCrossSimilarity(request: SegmentCrossSimilarityRequest): SegmentMatrix {
+  validateSegmentMatrix('segmentCrossSimilarity', request.x, request.xRows, request.xCols, 'x');
+  validateSegmentMatrix('segmentCrossSimilarity', request.y, request.yRows, request.yCols, 'y');
+  if (request.xRows !== request.yRows) {
+    throw new RangeError('segmentCrossSimilarity: feature dimensions must match');
+  }
+  assertNonNegativeInteger('segmentCrossSimilarity', request.k ?? 0, 'k');
+  return requireModule().segmentCrossSimilarity(
+    request.x,
+    request.xRows,
+    request.xCols,
+    request.y,
+    request.yRows,
+    request.yCols,
+    request.k ?? 0,
+    request.metric ?? 'cosine',
+    request.mode ?? 'connectivity',
+  );
+}
+
+/** Self-similarity recurrence matrix (librosa.segment.recurrence_matrix). */
+export function segmentRecurrenceMatrix(request: SegmentRecurrenceMatrixRequest): SegmentMatrix {
+  validateSegmentMatrix(
+    'segmentRecurrenceMatrix',
+    request.data,
+    request.rows,
+    request.cols,
+    'data',
+  );
+  assertNonNegativeInteger('segmentRecurrenceMatrix', request.k ?? 0, 'k');
+  assertNonNegativeInteger('segmentRecurrenceMatrix', request.width ?? 1, 'width');
+  return requireModule().segmentRecurrenceMatrix(
+    request.data,
+    request.rows,
+    request.cols,
+    request.k ?? 0,
+    request.width ?? 1,
+    request.sym ?? false,
+    request.metric ?? 'euclidean',
+    request.mode ?? 'connectivity',
+  );
+}
+
+/** Convert an `n × n` recurrence matrix to a lag matrix. */
+export function segmentRecurrenceToLag(request: SegmentRecurrenceToLagRequest): SegmentMatrix {
+  validateSegmentMatrix(
+    'segmentRecurrenceToLag',
+    request.recurrence,
+    request.n,
+    request.n,
+    'recurrence',
+  );
+  return requireModule().segmentRecurrenceToLag(
+    request.recurrence,
+    request.n,
+    request.pad ?? false,
+  );
+}
+
+/** Convert a lag matrix back to an `n × n` recurrence matrix. */
+export function segmentLagToRecurrence(request: SegmentLagToRecurrenceRequest): SegmentMatrix {
+  validateSegmentMatrix('segmentLagToRecurrence', request.lag, request.rows, request.lags, 'lag');
+  return requireModule().segmentLagToRecurrence(request.lag, request.rows, request.lags);
+}
+
+/** Refine frame boundaries by clustering within each parent segment. */
+export function segmentSubsegment(request: SegmentSubsegmentRequest): Int32Array {
+  validateSegmentMatrix('segmentSubsegment', request.data, request.rows, request.cols, 'data');
+  assertPositiveInteger('segmentSubsegment', request.nSegments ?? 4, 'nSegments');
+  return requireModule().segmentSubsegment(
+    request.data,
+    request.rows,
+    request.cols,
+    request.boundaries,
+    request.nSegments ?? 4,
+  );
+}
+
+/** Cluster feature columns and return one label per column. */
+export function segmentAgglomerative(request: SegmentAgglomerativeRequest): Int32Array {
+  validateSegmentMatrix('segmentAgglomerative', request.data, request.rows, request.cols, 'data');
+  assertPositiveInteger('segmentAgglomerative', request.k, 'k');
+  return requireModule().segmentAgglomerative(
+    request.data,
+    request.rows,
+    request.cols,
+    request.k,
+    request.linkage ?? 'average',
+  );
+}
+
+/** Enhance diagonal paths in an `n × n` recurrence matrix. */
+export function segmentPathEnhance(request: SegmentPathEnhanceRequest): SegmentMatrix {
+  validateSegmentMatrix(
+    'segmentPathEnhance',
+    request.recurrence,
+    request.n,
+    request.n,
+    'recurrence',
+  );
+  assertPositiveInteger('segmentPathEnhance', request.win, 'win');
+  assertPositiveInteger('segmentPathEnhance', request.maxRatio ?? 2, 'maxRatio');
+  assertNonNegativeInteger('segmentPathEnhance', request.minRatio ?? 0, 'minRatio');
+  assertPositiveInteger('segmentPathEnhance', request.nFilters ?? 7, 'nFilters');
+  return requireModule().segmentPathEnhance(
+    request.recurrence,
+    request.n,
+    request.win,
+    request.maxRatio ?? 2,
+    request.minRatio ?? 0,
+    request.nFilters ?? 7,
+  );
+}

package/src/feature_spectrogram.ts

@@ -4,6 +4,7 @@ import type {
   MelPowerResult,
   MelSpectrogramResult,
   MfccResult,
+  ReassignedSpectrogramResult,
   StftPowerResult,
   StftResult,
 } from './public_types';
@@ -49,6 +50,17 @@ export interface MfccRequest extends MelSpectrogramRequest {
   lifter?: number;
 }
 
+export interface MelDeltaRequest extends GuardedOptions {
+  features: Float32Array;
+  nFeatures: number;
+  nFrames: number;
+  width?: number;
+}
+export interface ReassignedSpectrogramRequest extends SpectrogramRequest {
+  refPower?: number;
+  fillNan?: boolean;
+}
+
 export interface MfccToMelRequest extends GuardedOptions {
   mfccCoefficients: Float32Array;
   nMfcc: number;
@@ -75,6 +87,16 @@ export interface MelToAudioRequest extends MelToStftRequest {
   hopLength?: number;
   nIter?: number;
 }
+export interface GriffinLimRequest extends GuardedOptions {
+  magnitude: Float32Array;
+  nBins: number;
+  nFrames: number;
+  sampleRate?: number;
+  nFft?: number;
+  hopLength?: number;
+  nIter?: number;
+  momentum?: number;
+}
 
 /** Canonical request form for Griffin-Lim reconstruction from MFCCs. */
 export interface MfccToAudioRequest extends MfccToMelRequest {
@@ -91,6 +113,8 @@ export interface TrimRequest extends GuardedOptions {
   samples: Float32Array;
   sampleRate: number;
   thresholdDb?: number;
+  frameLength?: number;
+  hopLength?: number;
 }
 
 function validateSpectrogramSamples(
@@ -161,19 +185,58 @@ export function trim(
   thresholdDb?: number,
   options?: GuardedOptions,
 ): Float32Array;
+export function trim(
+  samples: Float32Array,
+  sampleRate: number,
+  thresholdDb?: number,
+  frameLength?: number,
+  hopLength?: number,
+  options?: GuardedOptions,
+): Float32Array;
 export function trim(
   samples: Float32Array | TrimRequest,
   sampleRate = 22050,
   thresholdDb = -60.0,
+  frameLengthOrOptions?: number | GuardedOptions,
+  hopLength?: number,
   options: GuardedOptions = {},
 ): Float32Array {
   if (!(samples instanceof Float32Array)) {
     const r = samples;
-    return trim(r.samples, r.sampleRate, r.thresholdDb, r);
+    return trim(r.samples, r.sampleRate, r.thresholdDb, r.frameLength, r.hopLength, r);
+  }
+  if (frameLengthOrOptions === null) {
+    throw new TypeError('trim: frameLength must be an integer or options object');
+  }
+  if (
+    frameLengthOrOptions !== undefined &&
+    typeof frameLengthOrOptions !== 'number' &&
+    typeof frameLengthOrOptions !== 'object'
+  ) {
+    throw new TypeError('trim: frameLength must be an integer or options object');
   }
-  validateSpectrogramSamples('trim', samples, sampleRate, options);
+  const positionalOptions =
+    typeof frameLengthOrOptions === 'object' && frameLengthOrOptions !== null
+      ? frameLengthOrOptions
+      : options;
+  const positionalFrameLength =
+    typeof frameLengthOrOptions === 'number' ? frameLengthOrOptions : undefined;
+  const resolvedFrameLength = positionalFrameLength ?? 2048;
+  const resolvedHopLength = hopLength === undefined ? 512 : hopLength;
+  validateSpectrogramSamples('trim', samples, sampleRate, positionalOptions);
   assertFiniteScalar('trim', thresholdDb, 'thresholdDb');
-  return requireModule().trim(samples, sampleRate, thresholdDb);
+  assertPositiveInteger('trim', resolvedFrameLength, 'frameLength');
+  assertPositiveInteger('trim', resolvedHopLength, 'hopLength');
+  if (resolvedFrameLength > 2 ** 31 - 1 || resolvedHopLength > 2 ** 31 - 1) {
+    throw new RangeError('trim: frameLength and hopLength must fit in a signed 32-bit integer');
+  }
+  return requireModule().trimEx(
+    samples,
+    sampleRate,
+    thresholdDb,
+    resolvedFrameLength,
+    resolvedHopLength,
+  );
 }
 
 // ============================================================================
@@ -524,6 +587,90 @@ export function mfcc(
   );
 }
 
+/** First-order regression delta of a row-major feature matrix. */
+export function melDelta(request: MelDeltaRequest): Float32Array;
+export function melDelta(
+  features: Float32Array,
+  nFeatures: number,
+  nFrames: number,
+  width?: number,
+): Float32Array;
+export function melDelta(
+  features: Float32Array | MelDeltaRequest,
+  nFeatures?: number,
+  nFrames?: number,
+  width = 9,
+): Float32Array {
+  const request: MelDeltaRequest =
+    features instanceof Float32Array
+      ? { features, nFeatures: nFeatures ?? 0, nFrames: nFrames ?? 0, width }
+      : features;
+  assertPositiveInteger('melDelta', request.nFeatures, 'nFeatures');
+  assertPositiveInteger('melDelta', request.nFrames, 'nFrames');
+  assertPositiveInteger('melDelta', request.width ?? 9, 'width');
+  if ((request.width ?? 9) < 3 || (request.width ?? 9) % 2 === 0) {
+    throw new RangeError('melDelta: width must be an odd integer of at least 3');
+  }
+  if (request.features.length !== request.nFeatures * request.nFrames) {
+    throw new RangeError('melDelta: feature matrix length must equal nFeatures * nFrames');
+  }
+  return requireModule().melDelta(
+    request.features,
+    request.nFeatures,
+    request.nFrames,
+    request.width ?? 9,
+  );
+}
+
+/** Auger-Flandrin reassigned spectrogram (row-major [nBins x nFrames] arrays). */
+export function reassignedSpectrogram(
+  request: ReassignedSpectrogramRequest,
+): ReassignedSpectrogramResult;
+export function reassignedSpectrogram(
+  samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  refPower?: number,
+  fillNan?: boolean,
+): ReassignedSpectrogramResult;
+export function reassignedSpectrogram(
+  samples: Float32Array | ReassignedSpectrogramRequest,
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  refPower = 1e-6,
+  fillNan = false,
+): ReassignedSpectrogramResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    return reassignedSpectrogram(
+      request.samples,
+      request.sampleRate,
+      request.nFft,
+      request.hopLength,
+      request.refPower,
+      request.fillNan,
+    );
+  }
+  assertSamples('reassignedSpectrogram', samples, true);
+  assertSampleRate('reassignedSpectrogram', sampleRate);
+  assertPositiveInteger('reassignedSpectrogram', nFft, 'nFft');
+  assertPositiveInteger('reassignedSpectrogram', hopLength, 'hopLength');
+  assertFiniteScalar('reassignedSpectrogram', refPower, 'refPower');
+  if (refPower < 0) {
+    throw new RangeError('reassignedSpectrogram: refPower must be non-negative');
+  }
+  return requireModule().reassignedSpectrogram(
+    samples,
+    sampleRate,
+    nFft,
+    hopLength,
+    refPower,
+    fillNan,
+  );
+}
+
 // ============================================================================
 // Features - Inverse reconstruction
 // ============================================================================
@@ -663,6 +810,59 @@ export function melToAudio(
   );
 }
 
+/** Reconstruct audio from an STFT magnitude matrix via Griffin-Lim. */
+export function griffinLim(request: GriffinLimRequest): Float32Array;
+export function griffinLim(
+  magnitude: Float32Array,
+  nBins: number,
+  nFrames: number,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  nIter?: number,
+  momentum?: number,
+  options?: GuardedOptions,
+): Float32Array;
+export function griffinLim(
+  magnitude: Float32Array | GriffinLimRequest,
+  nBins = 0,
+  nFrames = 0,
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  nIter = 32,
+  momentum = 0.99,
+  options: GuardedOptions = {},
+): Float32Array {
+  if (!(magnitude instanceof Float32Array)) {
+    const request = magnitude;
+    return griffinLim(
+      request.magnitude,
+      request.nBins,
+      request.nFrames,
+      request.sampleRate,
+      request.nFft,
+      request.hopLength,
+      request.nIter,
+      request.momentum,
+      request,
+    );
+  }
+  assertSampleRate('griffinLim', sampleRate);
+  validateMatrix('griffinLim', magnitude, nBins, nFrames, 'magnitude', 'nBins', options);
+  validatePositiveIntegers('griffinLim', { nFft, hopLength, nIter });
+  return requireModule().griffinLim(
+    magnitude,
+    nBins,
+    nFrames,
+    sampleRate,
+    nFft,
+    hopLength,
+    nIter,
+    momentum,
+  );
+}
+
 /**
  * Invert MFCC coefficients back to a Mel power spectrogram. Mirrors
  * `feature::mfcc_to_mel`.

package/src/features.ts

@@ -1,5 +1,7 @@
 export {
   amplitudeToDb,
+  chirp,
+  clicks,
   cyclicTempogram,
   dbToAmplitude,
   dbToPower,
@@ -15,6 +17,7 @@ export {
   melToHz,
   midiToHz,
   noteToHz,
+  onsetBacktrack,
   padCenter,
   pcen,
   peakPick,
@@ -25,6 +28,7 @@ export {
   splitSilence,
   tempogram,
   timeToFrames,
+  tone,
   tonnetz,
   trimSilence,
   vectorNormalize,
@@ -47,7 +51,7 @@ export {
   vqt,
   vqtToAudio,
 } from './feature_music';
-export { pitchPyin, pitchYin } from './feature_pitch';
+export { noteSegments, piptrack, pitchPyin, pitchYin } from './feature_pitch';
 export { resample } from './feature_resample';
 export {
   decompose,
@@ -62,10 +66,18 @@ export {
   polyFeatures,
   remix,
   rmsEnergy,
+  segmentAgglomerative,
+  segmentCrossSimilarity,
+  segmentLagToRecurrence,
+  segmentPathEnhance,
+  segmentRecurrenceMatrix,
+  segmentRecurrenceToLag,
+  segmentSubsegment,
   spectralBandwidth,
   spectralCentroid,
   spectralContrast,
   spectralFlatness,
+  spectralFlux,
   spectralRolloff,
   zeroCrossingRate,
   zeroCrossings,
@@ -75,12 +87,15 @@ export {
   chroma,
   chromaCens,
   chromaCqt,
+  griffinLim,
+  melDelta,
   melSpectrogram,
   melToAudio,
   melToStft,
   mfcc,
   mfccToAudio,
   mfccToMel,
+  reassignedSpectrogram,
   stft,
   stftDb,
   trim,