@libraz/libsonare 1.5.4 → 1.6.0

package/src/effects_transform.ts

@@ -238,6 +238,10 @@ export function pitchShift(
 /**
  * Pitch-correct audio from a current MIDI note to a target MIDI note.
  *
+ * Applies one constant, immediate transpose with no retune glide and preserves
+ * the input buffer length. Use {@link pitchCorrectToMidiTimevarying} for a
+ * caller-supplied pitch contour.
+ *
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz
  * @param currentMidi - Detected/current MIDI note number
@@ -279,7 +283,8 @@ export function pitchCorrectToMidi(
  * the caller-supplied per-frame `f0Hz` contour and retunes every voiced frame
  * toward `targetMidi`, so vibrato/drift in the source is tracked rather than
  * flattened. `voiced` (non-zero = voiced) and `voicedProb` ([0,1]) are optional;
- * omitting them treats every frame as voiced.
+ * omitting them treats every frame as voiced. An `f0Hz` NaN is accepted only
+ * when the corresponding `voiced` entry is zero, matching pYIN output.
  *
  * @param samples - Audio samples (mono, float32)
  * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
@@ -354,7 +359,8 @@ export function pitchCorrectToMidiTimevarying(
  * Generalises {@link pitchCorrectToMidiTimevarying}: the same caller-supplied
  * per-frame `f0Hz` contour drives correction, but `options.mode` selects between
  * a fixed-MIDI target (`'midi'`, default) and scale quantisation (`'scale'`),
- * and the retune knobs shape natural-vs-robotic correction.
+ * and the retune knobs shape natural-vs-robotic correction. An `f0Hz` NaN is
+ * accepted only for a frame marked unvoiced.
  *
  * @param samples - Audio samples (mono, float32)
  * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
@@ -411,7 +417,7 @@ export function pitchCorrectTimevarying(
  * @param sampleRate - Sample rate in Hz
  * @param onsetSample - Note onset position in samples
  * @param offsetSample - Note offset position in samples
- * @param stretchRatio - Stretch ratio (0.5 = double duration, 2.0 = half duration)
+ * @param stretchRatio - Stretch ratio (0.5 = half duration, 2.0 = double duration)
  * @returns Audio with the note region stretched
  */
 export function noteStretch(request: NoteStretchRequest): Float32Array;
@@ -431,7 +437,7 @@ export function noteStretch(
     request.samples,
     request.sampleRate ?? 22050,
     request.onsetSample ?? 0,
-    request.offsetSample ?? 0,
+    request.offsetSample ?? request.samples.length,
     request.stretchRatio ?? 1.0,
   );
 }
@@ -454,7 +460,7 @@ export function noteMove(
     request.samples,
     request.sampleRate ?? 22050,
     request.onsetSample ?? 0,
-    request.offsetSample ?? 0,
+    request.offsetSample ?? request.samples.length,
     request.targetOnsetSample ?? 0,
   );
 }
@@ -464,7 +470,7 @@ export function noteMove(
  *
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz (default: 22050)
- * @param targetDb - Target peak level in dB (default: 0 dB = full scale)
+ * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale)
  * @returns Normalized audio
  */
 export function normalize(request: NormalizeRequest): Float32Array;

package/src/errors.ts

@@ -12,6 +12,7 @@ export enum ErrorCode {
   OutOfMemory = 5,
   NotSupported = 6,
   InvalidState = 7,
+  Cancelled = 8,
   Unknown = 99,
 }
 

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;
@@ -81,6 +185,14 @@ export interface PcenRequest {
   values: Float32Array;
   nBins: number;
   nFrames: number;
+  sampleRate?: number;
+  hopLength?: number;
+  timeConstant?: number;
+  gain?: number;
+  bias?: number;
+  power?: number;
+  eps?: number;
+  /** @deprecated Put PCEN fields directly on the request object. */
   options?: Record<string, number>;
 }
 export interface TempogramRequest {
@@ -89,6 +201,8 @@ export interface TempogramRequest {
   hopLength?: number;
   winLength?: number;
   mode?: TempogramMode;
+  center?: boolean;
+  norm?: boolean;
 }
 export interface CyclicTempogramRequest {
   onsetEnvelope: Float32Array;
@@ -383,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,
@@ -449,7 +575,17 @@ export function pcen(
 ): Float32Array {
   if (!(values instanceof Float32Array)) {
     const r = values;
-    return pcen(r.values, r.nBins, r.nFrames, r.options);
+    const {
+      values: requestValues,
+      nBins: requestBins,
+      nFrames: requestFrames,
+      options: legacyOptions,
+      ...flatOptions
+    } = r;
+    return pcen(requestValues, requestBins, requestFrames, {
+      ...legacyOptions,
+      ...flatOptions,
+    });
   }
   return requireModule().pcen(values, nBins, nFrames, options);
 }
@@ -474,6 +610,8 @@ export function tempogram(
   hopLength?: number,
   winLength?: number,
   mode?: TempogramMode,
+  center?: boolean,
+  norm?: boolean,
 ): WasmTempogramResult;
 export function tempogram(
   onsetEnvelope: Float32Array | TempogramRequest,
@@ -481,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 {
@@ -98,6 +100,9 @@ export interface LufsRequest extends ValidateOptions {
 export interface NnlsChromaRequest extends GuardedOptions {
   samples: Float32Array;
   sampleRate?: number;
+  enableStftBlend?: boolean;
+  stftBlendWeight?: number;
+  stftBlendNFft?: number;
 }
 
 function validateMusicSamples(
@@ -140,18 +145,24 @@ export function nnlsChroma(request: NnlsChromaRequest): WasmNnlsChromaResult;
 export function nnlsChroma(
   samples: Float32Array,
   sampleRate?: number,
-  options?: GuardedOptions,
+  options?: Omit<NnlsChromaRequest, 'samples' | 'sampleRate'>,
 ): WasmNnlsChromaResult;
 export function nnlsChroma(
   samples: Float32Array | NnlsChromaRequest,
   sampleRate = 22050,
-  options: GuardedOptions = {},
+  options: Omit<NnlsChromaRequest, 'samples' | 'sampleRate'> = {},
 ): WasmNnlsChromaResult {
   if (!(samples instanceof Float32Array)) {
     return nnlsChroma(samples.samples, samples.sampleRate, samples);
   }
   validateMusicSamples('nnlsChroma', samples, sampleRate, options);
-  return requireModule().nnlsChroma(samples, sampleRate);
+  return requireModule().nnlsChroma(
+    samples,
+    sampleRate,
+    options.enableStftBlend ?? true,
+    options.stftBlendWeight ?? 0.55,
+    options.stftBlendNFft ?? 4096,
+  );
 }
 
 /**
@@ -307,7 +318,8 @@ export function hybridCqt(
  * @param fmin - Minimum frequency in Hz (default: 32.70319566257483, C1)
  * @param nBins - Number of frequency bins (default: 84)
  * @param binsPerOctave - Bins per octave (default: 12)
- * @param gamma - Bandwidth offset; 0 is equivalent to CQT (default: 0)
+ * @param gamma - Bandwidth offset; negative selects the automatic ERB-derived
+ *   value, while 0 is equivalent to CQT (default: -1)
  * @returns VQT magnitude result (same shape as CQT)
  */
 export function vqt(request: VqtRequest): CqtResult;
@@ -328,7 +340,7 @@ export function vqt(
   fmin = 32.70319566257483,
   nBins = 84,
   binsPerOctave = 12,
-  gamma = 0,
+  gamma = -1,
   options: GuardedOptions = {},
 ): CqtResult {
   if (!(samples instanceof Float32Array)) {
@@ -348,9 +360,6 @@ export function vqt(
   validatePositiveIntegers('vqt', { hopLength, nBins, binsPerOctave });
   validateFrequencyBounds('vqt', fmin);
   assertFiniteScalar('vqt', gamma, 'gamma');
-  if (gamma < 0) {
-    throw new RangeError('vqt: gamma must be non-negative');
-  }
   return requireModule().vqt(samples, sampleRate, hopLength, fmin, nBins, binsPerOctave, gamma);
 }
 
@@ -465,7 +474,7 @@ export function vqtToAudio(
   hopLength = 512,
   fmin = 32.70319566257483,
   binsPerOctave = 12,
-  gamma = 0,
+  gamma = -1,
   nIter = 32,
   options: GuardedOptions = {},
 ): Float32Array {
@@ -497,9 +506,6 @@ export function vqtToAudio(
     options,
   );
   assertFiniteScalar('vqtToAudio', gamma, 'gamma');
-  if (gamma < 0) {
-    throw new RangeError('vqtToAudio: gamma must be non-negative');
-  }
   return requireModule().vqtToAudio(
     magnitude,
     nBins,
@@ -544,8 +550,8 @@ export function analyzeSections(
     hopLength: options.hopLength ?? 512,
   });
   assertFiniteScalar('analyzeSections', options.minSectionSec ?? 4.0, 'minSectionSec');
-  if ((options.minSectionSec ?? 4.0) <= 0) {
-    throw new RangeError('analyzeSections: minSectionSec must be positive');
+  if ((options.minSectionSec ?? 4.0) < 0) {
+    throw new RangeError('analyzeSections: minSectionSec must be non-negative');
   }
   // The embind value marshalling returns an array whose constructor is not this
   // realm's Array; chaining .map() onto it propagates that constructor via
@@ -580,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`.
    */
@@ -756,6 +762,8 @@ export function fourierTempogram(
   sampleRate?: number,
   hopLength?: number,
   winLength?: number,
+  center?: boolean,
+  norm?: boolean,
   options?: GuardedOptions,
 ): WasmFourierTempogramResult;
 export function fourierTempogram(
@@ -763,6 +771,8 @@ export function fourierTempogram(
   sampleRate = 22050,
   hopLength = 512,
   winLength = 384,
+  center = true,
+  norm = true,
   options: GuardedOptions = {},
 ): WasmFourierTempogramResult {
   if (!(onsetEnvelope instanceof Float32Array)) {
@@ -772,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();
@@ -18,8 +18,8 @@ function requireModule() {
  * @param hopLength - Hop length (default: 512)
  * @param fmin - Minimum frequency in Hz (default: 65)
  * @param fmax - Maximum frequency in Hz (default: 2093)
- * @param threshold - YIN threshold (default: 0.3)
- * @param fillNa - If true, return 0 for unvoiced f0 frames; otherwise keep NaN (default: false)
+ * @param threshold - YIN threshold (default: 0.1)
+ * @param fillNa - Retained for compatibility; YIN always returns a finite per-frame estimate.
  * @returns Pitch detection result
  */
 export interface PitchYinRequest {
@@ -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,
@@ -51,7 +96,7 @@ export function pitchYin(
   hopLength = 512,
   fmin = 65.0,
   fmax = 2093.0,
-  threshold = 0.3,
+  threshold = 0.1,
   fillNa = false,
 ): PitchResult {
   if (!(samples instanceof Float32Array)) {
@@ -88,7 +133,7 @@ export function pitchYin(
  * @param hopLength - Hop length (default: 512)
  * @param fmin - Minimum frequency in Hz (default: 65)
  * @param fmax - Maximum frequency in Hz (default: 2093)
- * @param threshold - YIN threshold (default: 0.3)
+ * @param threshold - YIN threshold (default: 0.1)
  * @param fillNa - If true, return 0 for unvoiced f0 frames; otherwise keep NaN (default: false)
  * @returns Pitch detection result
  */
@@ -112,7 +157,7 @@ export function pitchPyin(
   hopLength = 512,
   fmin = 65.0,
   fmax = 2093.0,
-  threshold = 0.3,
+  threshold = 0.1,
   fillNa = false,
 ): PitchResult {
   if (!(samples instanceof 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,
+  });
+}