@libraz/libsonare 1.5.5 → 1.6.0

package/src/feature_core.ts

@@ -11,6 +11,85 @@ function requireModule() {
   return getSonareModule();
 }
 
+export function tone(request?: ToneRequest): Float32Array;
+export function tone(
+  frequency?: number,
+  sampleRate?: number,
+  duration?: number,
+  phase?: number,
+  amplitude?: number,
+): Float32Array;
+export function tone(
+  frequency: number | ToneRequest = 440,
+  sampleRate = 22050,
+  duration = 1,
+  phase = 0,
+  amplitude = 1,
+): Float32Array {
+  const request =
+    typeof frequency === 'number'
+      ? { frequency, sampleRate, duration, phase, amplitude }
+      : frequency;
+  return requireModule().tone(
+    request.frequency ?? 440,
+    request.sampleRate ?? 22050,
+    request.duration ?? 1,
+    request.phase ?? 0,
+    request.amplitude ?? 1,
+  );
+}
+
+export function chirp(request?: ChirpRequest): Float32Array;
+export function chirp(
+  fmin?: number,
+  fmax?: number,
+  sampleRate?: number,
+  duration?: number,
+  linear?: boolean,
+): Float32Array;
+export function chirp(
+  fmin: number | ChirpRequest = 440,
+  fmax = 880,
+  sampleRate = 22050,
+  duration = 1,
+  linear = true,
+): Float32Array {
+  const request = typeof fmin === 'number' ? { fmin, fmax, sampleRate, duration, linear } : fmin;
+  return requireModule().chirp(
+    request.fmin ?? 440,
+    request.fmax ?? 880,
+    request.sampleRate ?? 22050,
+    request.duration ?? 1,
+    request.linear ?? true,
+  );
+}
+
+export function clicks(request: ClicksRequest): Float32Array;
+export function clicks(
+  times: Float32Array,
+  sampleRate?: number,
+  length?: number,
+  frequency?: number,
+  clickDuration?: number,
+): Float32Array;
+export function clicks(
+  times: Float32Array | ClicksRequest,
+  sampleRate = 22050,
+  length = 0,
+  frequency = 1000,
+  clickDuration = 0.1,
+): Float32Array {
+  const request =
+    times instanceof Float32Array ? { times, sampleRate, length, frequency, clickDuration } : times;
+  return requireModule().clicks(
+    request.times,
+    request.sampleRate ?? 22050,
+    request.length ?? 0,
+    request.frequency ?? 1000,
+    request.clickDuration ?? 0.1,
+  );
+}
+
 export interface DbConversionRequest {
   values: Float32Array;
   ref?: number;
@@ -30,6 +109,27 @@ export interface FrameSignalRequest {
   frameLength: number;
   hopLength: number;
 }
+export interface ToneRequest {
+  frequency?: number;
+  sampleRate?: number;
+  duration?: number;
+  phase?: number;
+  amplitude?: number;
+}
+export interface ChirpRequest {
+  fmin?: number;
+  fmax?: number;
+  sampleRate?: number;
+  duration?: number;
+  linear?: boolean;
+}
+export interface ClicksRequest {
+  times: Float32Array;
+  sampleRate?: number;
+  length?: number;
+  frequency?: number;
+  clickDuration?: number;
+}
 /** Canonical request form for pre/de-emphasis filters. */
 export interface EmphasisRequest {
   samples: Float32Array;
@@ -55,6 +155,10 @@ export interface FixFramesRequest {
   xMax?: number;
   pad?: boolean;
 }
+export interface OnsetBacktrackRequest {
+  events: Int32Array;
+  energy: Float32Array;
+}
 /** Canonical request form for peak selection. */
 export interface PeakPickRequest {
   values: Float32Array;
@@ -97,6 +201,8 @@ export interface TempogramRequest {
   hopLength?: number;
   winLength?: number;
   mode?: TempogramMode;
+  center?: boolean;
+  norm?: boolean;
 }
 export interface CyclicTempogramRequest {
   onsetEnvelope: Float32Array;
@@ -391,6 +497,18 @@ export function fixFrames(
   return requireModule().fixFrames(frames, xMin, xMax, pad);
 }
 
+export function onsetBacktrack(request: OnsetBacktrackRequest): Int32Array;
+export function onsetBacktrack(events: Int32Array, energy: Float32Array): Int32Array;
+export function onsetBacktrack(
+  events: Int32Array | OnsetBacktrackRequest,
+  energy?: Float32Array,
+): Int32Array {
+  if (!(events instanceof Int32Array)) {
+    return onsetBacktrack(events.events, events.energy);
+  }
+  return requireModule().onsetBacktrack(events, energy as Float32Array);
+}
+
 export function peakPick(request: PeakPickRequest): Int32Array;
 export function peakPick(
   values: Float32Array,
@@ -492,6 +610,8 @@ export function tempogram(
   hopLength?: number,
   winLength?: number,
   mode?: TempogramMode,
+  center?: boolean,
+  norm?: boolean,
 ): WasmTempogramResult;
 export function tempogram(
   onsetEnvelope: Float32Array | TempogramRequest,
@@ -499,12 +619,30 @@ export function tempogram(
   hopLength = 512,
   winLength = 384,
   mode: TempogramMode = 'autocorrelation',
+  center = true,
+  norm = true,
 ): WasmTempogramResult {
   if (!(onsetEnvelope instanceof Float32Array)) {
     const r = onsetEnvelope;
-    return tempogram(r.onsetEnvelope, r.sampleRate, r.hopLength, r.winLength, r.mode);
+    return tempogram(
+      r.onsetEnvelope,
+      r.sampleRate,
+      r.hopLength,
+      r.winLength,
+      r.mode,
+      r.center,
+      r.norm,
+    );
   }
-  return requireModule().tempogram(onsetEnvelope, sampleRate, hopLength, winLength, mode);
+  return requireModule().tempogram(
+    onsetEnvelope,
+    sampleRate,
+    hopLength,
+    winLength,
+    mode,
+    center,
+    norm,
+  );
 }
 
 export function cyclicTempogram(request: CyclicTempogramRequest): WasmCyclicTempogramResult;

package/src/feature_music.ts

@@ -58,6 +58,8 @@ export interface FourierTempogramRequest extends GuardedOptions {
   sampleRate?: number;
   hopLength?: number;
   winLength?: number;
+  center?: boolean;
+  norm?: boolean;
 }
 
 export interface TempogramRatioRequest extends GuardedOptions {
@@ -584,7 +586,7 @@ export interface MelodyOptions {
    */
   usePyin?: boolean;
   /**
-   * When {@link usePyin} is `true`, reflect-pad by `frameLength / 2` so frame
+   * When {@link usePyin} is `true`, zero-pad by `frameLength / 2` so frame
    * `i` is centered at `i * hopLength` (matches `librosa.pyin(center=True)`).
    * Ignored by the plain-YIN path. Defaults to `true`.
    */
@@ -760,6 +762,8 @@ export function fourierTempogram(
   sampleRate?: number,
   hopLength?: number,
   winLength?: number,
+  center?: boolean,
+  norm?: boolean,
   options?: GuardedOptions,
 ): WasmFourierTempogramResult;
 export function fourierTempogram(
@@ -767,6 +771,8 @@ export function fourierTempogram(
   sampleRate = 22050,
   hopLength = 512,
   winLength = 384,
+  center = true,
+  norm = true,
   options: GuardedOptions = {},
 ): WasmFourierTempogramResult {
   if (!(onsetEnvelope instanceof Float32Array)) {
@@ -776,13 +782,22 @@ export function fourierTempogram(
       request.sampleRate,
       request.hopLength,
       request.winLength,
+      request.center,
+      request.norm,
       request,
     );
   }
   assertSampleRate('fourierTempogram', sampleRate);
   assertSamples('fourierTempogram', onsetEnvelope, options.validate !== false, 'onsetEnvelope');
   validatePositiveIntegers('fourierTempogram', { hopLength, winLength });
-  return requireModule().fourierTempogram(onsetEnvelope, sampleRate, hopLength, winLength);
+  return requireModule().fourierTempogram(
+    onsetEnvelope,
+    sampleRate,
+    hopLength,
+    winLength,
+    center,
+    norm,
+  );
 }
 
 /**

package/src/feature_pitch.ts

@@ -1,5 +1,5 @@
 import { getSonareModule } from './module_state';
-import type { PitchResult } from './public_types';
+import type { NoteSegment, PiptrackResult, PitchResult } from './public_types';
 
 function requireModule() {
   return getSonareModule();
@@ -33,6 +33,51 @@ export interface PitchYinRequest {
   fillNa?: boolean;
 }
 
+export interface PiptrackRequest {
+  samples: Float32Array;
+  sampleRate?: number;
+  nFft?: number;
+  hopLength?: number;
+  fmin?: number;
+  fmax?: number;
+  threshold?: number;
+}
+
+/** Per-bin spectral pitch candidates and peak magnitudes (librosa.piptrack). */
+export function piptrack(request: PiptrackRequest): PiptrackResult;
+export function piptrack(
+  samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  fmin?: number,
+  fmax?: number,
+  threshold?: number,
+): PiptrackResult;
+export function piptrack(
+  samples: Float32Array | PiptrackRequest,
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  fmin = 150,
+  fmax = 4000,
+  threshold = 0.1,
+): PiptrackResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    return piptrack(
+      request.samples,
+      request.sampleRate,
+      request.nFft,
+      request.hopLength,
+      request.fmin,
+      request.fmax,
+      request.threshold,
+    );
+  }
+  return requireModule().piptrack(samples, sampleRate, nFft, hopLength, fmin, fmax, threshold);
+}
+
 export function pitchYin(request: PitchYinRequest): PitchResult;
 export function pitchYin(
   samples: Float32Array,
@@ -139,3 +184,27 @@ export function pitchPyin(
     fillNa,
   );
 }
+
+/** Parameters for segmenting an F0 track into stable monophonic notes. */
+export interface NoteSegmentsRequest {
+  f0Hz: Float32Array;
+  voicedProb: Float32Array;
+  frameRate: number;
+  segmentationThresholdCents?: number;
+  minNoteMs?: number;
+  referenceHz?: number;
+}
+
+/**
+ * Segment a caller-supplied monophonic F0 track into stable note regions.
+ *
+ * `f0Hz` and `voicedProb` must have the same non-zero length. Zero-Hz frames
+ * and probabilities below 0.5 are treated as unvoiced.
+ */
+export function noteSegments(request: NoteSegmentsRequest): NoteSegment[] {
+  return requireModule().noteSegments(request.f0Hz, request.voicedProb, request.frameRate, {
+    segmentationThresholdCents: request.segmentationThresholdCents,
+    minNoteMs: request.minNoteMs,
+    referenceHz: request.referenceHz,
+  });
+}

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,7 +7,13 @@ 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();
@@ -76,6 +83,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>;
@@ -537,23 +613,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 +705,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 +792,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,
+  );
+}