@libraz/libsonare 1.5.5 → 1.7.0

package/src/effects_transform.ts

@@ -14,12 +14,65 @@ 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 };
+}
+
+export type NormalizeMode = 'peak' | 'rms';
+
+function resolveNormalizeMode(value: unknown): NormalizeMode {
+  if (value === undefined) {
+    return 'peak';
+  }
+  if (typeof value !== 'string') {
+    throw new TypeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  if (value !== 'peak' && value !== 'rms') {
+    throw new RangeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  return value;
+}
+
+function resolveHardMask(value: unknown, fnName: string): 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 HPSS. */
 export interface HpssRequest {
   samples: Float32Array;
   sampleRate?: number;
   kernelHarmonic?: number;
   kernelPercussive?: number;
+  nFft?: number;
+  hopLength?: number;
+  hardMask?: boolean;
 }
 
 export interface HarmonicRequest extends ValidateOptions {
@@ -36,12 +89,16 @@ export interface TimeStretchRequest extends ValidateOptions {
   samples: Float32Array;
   sampleRate?: number;
   rate: number;
+  nFft?: number;
+  hopLength?: number;
 }
 
 export interface PitchShiftRequest extends ValidateOptions {
   samples: Float32Array;
   sampleRate?: number;
   semitones: number;
+  nFft?: number;
+  hopLength?: number;
 }
 
 export interface PitchCorrectToMidiRequest extends ValidateOptions {
@@ -81,6 +138,7 @@ export interface NormalizeRequest extends ValidateOptions {
   samples: Float32Array;
   sampleRate?: number;
   targetDb?: number;
+  mode?: NormalizeMode;
 }
 
 export interface SpectralEditRequest extends SpectralEditOptions, ValidateOptions {
@@ -108,22 +166,33 @@ export function hpss(
   sampleRate?: number,
   kernelHarmonic?: number,
   kernelPercussive?: number,
+  nFft?: number,
+  hopLength?: number,
+  hardMask?: boolean,
 ): HpssResult;
 export function hpss(
   samples: Float32Array | HpssRequest,
   sampleRate = 22050,
   kernelHarmonic = 31,
   kernelPercussive = 31,
+  nFft?: number,
+  hopLength?: number,
+  hardMask?: boolean,
 ): HpssResult {
   const request =
     samples instanceof Float32Array
-      ? { samples, sampleRate, kernelHarmonic, kernelPercussive }
+      ? { samples, sampleRate, kernelHarmonic, kernelPercussive, nFft, hopLength, hardMask }
       : samples;
-  return requireModule().hpss(
+  const fftOptions = resolveEffectFftOptions('hpss', request.nFft, request.hopLength);
+  const resolvedHardMask = resolveHardMask(request.hardMask, 'hpss');
+  return requireModule().hpssEx(
     request.samples,
     request.sampleRate ?? 22050,
     request.kernelHarmonic ?? 31,
     request.kernelPercussive ?? 31,
+    fftOptions.nFft,
+    fftOptions.hopLength,
+    resolvedHardMask,
   );
 }
 
@@ -188,18 +257,56 @@ export function timeStretch(
   rate: number,
   options?: ValidateOptions,
 ): Float32Array;
+export function timeStretch(
+  samples: Float32Array,
+  sampleRate: number,
+  rate: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: ValidateOptions,
+): Float32Array;
 export function timeStretch(
   samples: Float32Array | TimeStretchRequest,
   sampleRate?: number,
   rate?: number,
+  nFftOrOptions?: number | ValidateOptions,
+  hopLength?: number,
   options: ValidateOptions = {},
 ): Float32Array {
+  if (
+    nFftOrOptions !== undefined &&
+    nFftOrOptions !== null &&
+    typeof nFftOrOptions !== 'number' &&
+    typeof nFftOrOptions !== 'object'
+  ) {
+    throw new TypeError('timeStretch: nFft must be an integer or options object');
+  }
+  if (nFftOrOptions === null) {
+    throw new TypeError('timeStretch: nFft must be an integer or options object');
+  }
+  const positionalOptions =
+    typeof nFftOrOptions === 'object' && nFftOrOptions !== null ? nFftOrOptions : options;
+  const positionalNFft = typeof nFftOrOptions === 'number' ? nFftOrOptions : undefined;
   const request: TimeStretchRequest =
     samples instanceof Float32Array
-      ? { samples, sampleRate, rate: rate as number, ...options }
+      ? {
+          samples,
+          sampleRate,
+          rate: rate as number,
+          nFft: positionalNFft,
+          hopLength,
+          ...positionalOptions,
+        }
       : samples;
   assertSamples('timeStretch', request.samples, request.validate !== false);
-  return requireModule().timeStretch(request.samples, request.sampleRate ?? 22050, request.rate);
+  const fftOptions = resolveEffectFftOptions('timeStretch', request.nFft, request.hopLength);
+  return requireModule().timeStretchEx(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.rate,
+    fftOptions.nFft,
+    fftOptions.hopLength,
+  );
 }
 
 /**
@@ -217,21 +324,55 @@ export function pitchShift(
   semitones: number,
   options?: ValidateOptions,
 ): Float32Array;
+export function pitchShift(
+  samples: Float32Array,
+  sampleRate: number,
+  semitones: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: ValidateOptions,
+): Float32Array;
 export function pitchShift(
   samples: Float32Array | PitchShiftRequest,
   sampleRate?: number,
   semitones?: number,
+  nFftOrOptions?: number | ValidateOptions,
+  hopLength?: number,
   options: ValidateOptions = {},
 ): Float32Array {
+  if (
+    nFftOrOptions !== undefined &&
+    nFftOrOptions !== null &&
+    typeof nFftOrOptions !== 'number' &&
+    typeof nFftOrOptions !== 'object'
+  ) {
+    throw new TypeError('pitchShift: nFft must be an integer or options object');
+  }
+  if (nFftOrOptions === null) {
+    throw new TypeError('pitchShift: nFft must be an integer or options object');
+  }
+  const positionalOptions =
+    typeof nFftOrOptions === 'object' && nFftOrOptions !== null ? nFftOrOptions : options;
+  const positionalNFft = typeof nFftOrOptions === 'number' ? nFftOrOptions : undefined;
   const request: PitchShiftRequest =
     samples instanceof Float32Array
-      ? { samples, sampleRate, semitones: semitones as number, ...options }
+      ? {
+          samples,
+          sampleRate,
+          semitones: semitones as number,
+          nFft: positionalNFft,
+          hopLength,
+          ...positionalOptions,
+        }
       : samples;
   assertSamples('pitchShift', request.samples, request.validate !== false);
-  return requireModule().pitchShift(
+  const fftOptions = resolveEffectFftOptions('pitchShift', request.nFft, request.hopLength);
+  return requireModule().pitchShiftEx(
     request.samples,
     request.sampleRate ?? 22050,
     request.semitones,
+    fftOptions.nFft,
+    fftOptions.hopLength,
   );
 }
 
@@ -466,11 +607,13 @@ export function noteMove(
 }
 
 /**
- * Normalize audio to target peak level.
+ * Normalize audio to a target peak or RMS level.
  *
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz (default: 22050)
- * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale)
+ * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale).
+ *   For `mode: 'peak'`, this is the peak target; for `mode: 'rms'`, this is the RMS target.
+ * @param mode - Normalization mode: `'peak'` (default) or `'rms'`.
  * @returns Normalized audio
  */
 export function normalize(request: NormalizeRequest): Float32Array;
@@ -480,19 +623,45 @@ export function normalize(
   targetDb?: number,
   options?: ValidateOptions,
 ): Float32Array;
+export function normalize(
+  samples: Float32Array,
+  sampleRate: number,
+  targetDb?: number,
+  mode?: NormalizeMode,
+  options?: ValidateOptions,
+): Float32Array;
 export function normalize(
   samples: Float32Array | NormalizeRequest,
   sampleRate?: number,
   targetDb = 0.0,
+  modeOrOptions: NormalizeMode | ValidateOptions = 'peak',
   options: ValidateOptions = {},
 ): Float32Array {
+  if (
+    modeOrOptions !== undefined &&
+    modeOrOptions !== null &&
+    typeof modeOrOptions !== 'string' &&
+    typeof modeOrOptions !== 'object'
+  ) {
+    throw new TypeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  if (modeOrOptions === null) {
+    throw new TypeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  const positionalOptions =
+    typeof modeOrOptions === 'object' && modeOrOptions !== null ? modeOrOptions : options;
+  const positionalMode = typeof modeOrOptions === 'string' ? modeOrOptions : undefined;
   const request: NormalizeRequest =
-    samples instanceof Float32Array ? { samples, sampleRate, targetDb, ...options } : samples;
+    samples instanceof Float32Array
+      ? { samples, sampleRate, targetDb, mode: positionalMode, ...positionalOptions }
+      : samples;
   assertSamples('normalize', request.samples, request.validate !== false);
-  return requireModule().normalize(
+  const mode = resolveNormalizeMode(request.mode);
+  return requireModule().normalizeEx(
     request.samples,
     request.sampleRate ?? 22050,
     request.targetDb ?? 0.0,
+    mode,
   );
 }
 

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;
@@ -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 {
@@ -101,6 +103,7 @@ export interface NnlsChromaRequest extends GuardedOptions {
   enableStftBlend?: boolean;
   stftBlendWeight?: number;
   stftBlendNFft?: number;
+  hopLength?: number;
 }
 
 function validateMusicSamples(
@@ -154,12 +157,18 @@ export function nnlsChroma(
     return nnlsChroma(samples.samples, samples.sampleRate, samples);
   }
   validateMusicSamples('nnlsChroma', samples, sampleRate, options);
-  return requireModule().nnlsChroma(
+  const hopLength = options.hopLength === undefined ? 512 : options.hopLength;
+  assertPositiveInteger('nnlsChroma', hopLength, 'hopLength');
+  if (hopLength > 2 ** 31 - 1) {
+    throw new RangeError('nnlsChroma: hopLength must fit in a signed 32-bit integer');
+  }
+  return requireModule().nnlsChromaEx(
     samples,
     sampleRate,
     options.enableStftBlend ?? true,
     options.stftBlendWeight ?? 0.55,
     options.stftBlendNFft ?? 4096,
+    hopLength,
   );
 }
 
@@ -584,7 +593,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 +769,8 @@ export function fourierTempogram(
   sampleRate?: number,
   hopLength?: number,
   winLength?: number,
+  center?: boolean,
+  norm?: boolean,
   options?: GuardedOptions,
 ): WasmFourierTempogramResult;
 export function fourierTempogram(
@@ -767,6 +778,8 @@ export function fourierTempogram(
   sampleRate = 22050,
   hopLength = 512,
   winLength = 384,
+  center = true,
+  norm = true,
   options: GuardedOptions = {},
 ): WasmFourierTempogramResult {
   if (!(onsetEnvelope instanceof Float32Array)) {
@@ -776,13 +789,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,
+  });
+}