@libraz/libsonare 1.7.2 → 1.8.0

package/src/feature_spectrogram.ts

@@ -1,14 +1,19 @@
+/**
+ * Spectrogram and chroma representations, and the silence trim that shares
+ * their input checks.
+ */
+
+import type { GuardedOptions } from './_feature_validation';
+import { validateMelFrequencyRange, validatePositiveIntegers } from './_feature_validation';
+import { resolveFftOptions } from './_fft_options';
 import { getSonareModule } from './module_state';
 import type {
   ChromaResult,
-  MelPowerResult,
   MelSpectrogramResult,
   MfccResult,
   ReassignedSpectrogramResult,
-  StftPowerResult,
   StftResult,
 } from './public_types';
-import type { ValidateOptions } from './validation';
 import {
   assertFiniteScalar,
   assertPositiveInteger,
@@ -20,8 +25,6 @@ function requireModule() {
   return getSonareModule();
 }
 
-type GuardedOptions = ValidateOptions;
-
 /** Canonical request form for basic frame-based spectrogram features. */
 export interface SpectrogramRequest extends GuardedOptions {
   samples: Float32Array;
@@ -30,6 +33,13 @@ export interface SpectrogramRequest extends GuardedOptions {
   hopLength?: number;
 }
 
+/**
+ * Options for the constant-Q chroma variants.
+ *
+ * Carries no `nFft`: these are built on a constant-Q transform, which resolves
+ * frequency through per-bin filter lengths rather than a framed FFT, so there
+ * is no FFT size to set. Use `chroma` for the STFT-framed chromagram.
+ */
 export interface ChromaSpectrogramRequest extends GuardedOptions {
   samples: Float32Array;
   sampleRate?: number;
@@ -38,6 +48,34 @@ export interface ChromaSpectrogramRequest extends GuardedOptions {
   binsPerOctave?: number;
 }
 
+/**
+ * Options for the bass-focused chroma.
+ *
+ * Unlike {@link ChromaSpectrogramRequest} this carries no `binsPerOctave`: the
+ * bass chroma fixes its bin count and its lowest frequency together, so the
+ * resolution is not independently settable through this entry point.
+ */
+export interface BassChromaSpectrogramRequest extends GuardedOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+  hopLength?: number;
+  nChroma?: number;
+}
+
+/**
+ * Compile-time guard for the two request shapes above. A field the entry point
+ * cannot forward is worse than a missing one: it type-checks, runs, and returns
+ * the default silently. These aliases fail to compile if either field appears,
+ * so adding one has to be a deliberate act.
+ */
+type AbsentKey<T extends never> = T;
+
+type _ChromaRequestHasNoFftSize = AbsentKey<Extract<keyof ChromaSpectrogramRequest, 'nFft'>>;
+
+type _BassChromaRequestHasNoResolutionControls = AbsentKey<
+  Extract<keyof BassChromaSpectrogramRequest, 'nFft' | 'binsPerOctave'>
+>;
+
 export interface MelSpectrogramRequest extends SpectrogramRequest {
   nMels?: number;
   fmin?: number;
@@ -56,59 +94,12 @@ export interface MelDeltaRequest extends GuardedOptions {
   nFrames: number;
   width?: number;
 }
+
 export interface ReassignedSpectrogramRequest extends SpectrogramRequest {
   refPower?: number;
   fillNan?: boolean;
 }
 
-export interface MfccToMelRequest extends GuardedOptions {
-  mfccCoefficients: Float32Array;
-  nMfcc: number;
-  nFrames: number;
-  nMels?: number;
-  /** Lifter used by the forward MFCC transform; zero means no liftering. */
-  lifter?: number;
-}
-
-/** Canonical request form for reconstruction from a Mel power spectrogram. */
-export interface MelToStftRequest extends GuardedOptions {
-  melPower: Float32Array;
-  nMels: number;
-  nFrames: number;
-  sampleRate?: number;
-  nFft?: number;
-  fmin?: number;
-  fmax?: number;
-  htk?: boolean;
-}
-
-/** Canonical request form for Griffin-Lim reconstruction from Mel power. */
-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 {
-  sampleRate?: number;
-  nFft?: number;
-  hopLength?: number;
-  fmin?: number;
-  fmax?: number;
-  nIter?: number;
-  htk?: boolean;
-}
-
 export interface TrimRequest extends GuardedOptions {
   samples: Float32Array;
   sampleRate: number;
@@ -127,49 +118,6 @@ function validateSpectrogramSamples(
   assertSamples(fnName, samples, options.validate !== false);
 }
 
-function validatePositiveIntegers(fnName: string, values: Record<string, number>): void {
-  for (const [name, value] of Object.entries(values)) {
-    assertPositiveInteger(fnName, value, name);
-  }
-}
-
-function validateMelFrequencyRange(
-  fnName: string,
-  fmin: number,
-  fmax: number,
-  sampleRate: number,
-): void {
-  assertFiniteScalar(fnName, fmin, 'fmin');
-  assertFiniteScalar(fnName, fmax, 'fmax');
-  if (fmin < 0) {
-    throw new RangeError(`${fnName}: fmin must be non-negative`);
-  }
-  if (fmax < 0) {
-    throw new RangeError(`${fnName}: fmax must be non-negative`);
-  }
-  const effectiveFmax = fmax === 0 ? sampleRate / 2 : fmax;
-  if (effectiveFmax <= fmin) {
-    throw new RangeError(`${fnName}: fmax must be greater than fmin`);
-  }
-}
-
-function validateMatrix(
-  fnName: string,
-  data: Float32Array,
-  rows: number,
-  frames: number,
-  dataName: string,
-  rowName: string,
-  options: GuardedOptions = {},
-): void {
-  validatePositiveIntegers(fnName, { [rowName]: rows, nFrames: frames });
-  assertSamples(fnName, data, options.validate !== false, dataName);
-  const expectedLength = rows * frames;
-  if (!Number.isSafeInteger(expectedLength) || data.length !== expectedLength) {
-    throw new RangeError(`${fnName}: ${dataName} length must equal ${rowName} * nFrames`);
-  }
-}
-
 /**
  * Trim silence from beginning and end of audio.
  *
@@ -272,8 +220,8 @@ export function stft(
     return stft(request.samples, request.sampleRate, request.nFft, request.hopLength, request);
   }
   validateSpectrogramSamples('stft', samples, sampleRate, options);
-  validatePositiveIntegers('stft', { nFft, hopLength });
-  return requireModule().stft(samples, sampleRate, nFft, hopLength);
+  const fft = resolveFftOptions('stft', nFft, hopLength);
+  return requireModule().stft(samples, sampleRate, fft.nFft, fft.hopLength);
 }
 
 /**
@@ -309,8 +257,8 @@ export function stftDb(
     return stftDb(request.samples, request.sampleRate, request.nFft, request.hopLength, request);
   }
   validateSpectrogramSamples('stftDb', samples, sampleRate, options);
-  validatePositiveIntegers('stftDb', { nFft, hopLength });
-  return requireModule().stftDb(samples, sampleRate, nFft, hopLength);
+  const fft = resolveFftOptions('stftDb', nFft, hopLength);
+  return requireModule().stftDb(samples, sampleRate, fft.nFft, fft.hopLength);
 }
 
 /**
@@ -412,7 +360,7 @@ export function chromaCqt(
  * @param nChroma - Number of chroma bins (default: 12)
  * @returns Chroma result
  */
-export function bassChroma(request: ChromaSpectrogramRequest): ChromaResult;
+export function bassChroma(request: BassChromaSpectrogramRequest): ChromaResult;
 export function bassChroma(
   samples: Float32Array,
   sampleRate?: number,
@@ -421,7 +369,7 @@ export function bassChroma(
   options?: GuardedOptions,
 ): ChromaResult;
 export function bassChroma(
-  samples: Float32Array | ChromaSpectrogramRequest,
+  samples: Float32Array | BassChromaSpectrogramRequest,
   sampleRate = 22050,
   hopLength = 512,
   nChroma = 12,
@@ -498,13 +446,14 @@ export function melSpectrogram(
     );
   }
   validateSpectrogramSamples('melSpectrogram', samples, sampleRate, options);
-  validatePositiveIntegers('melSpectrogram', { nFft, hopLength, nMels });
+  const fft = resolveFftOptions('melSpectrogram', nFft, hopLength);
+  validatePositiveIntegers('melSpectrogram', { nMels });
   validateMelFrequencyRange('melSpectrogram', fmin, fmax, sampleRate);
   return requireModule().melSpectrogram(
     samples,
     sampleRate,
-    nFft,
-    hopLength,
+    fft.nFft,
+    fft.hopLength,
     nMels,
     fmin,
     fmax,
@@ -571,13 +520,14 @@ export function mfcc(
     );
   }
   validateSpectrogramSamples('mfcc', samples, sampleRate, options);
-  validatePositiveIntegers('mfcc', { nFft, hopLength, nMels, nMfcc });
+  const fft = resolveFftOptions('mfcc', nFft, hopLength);
+  validatePositiveIntegers('mfcc', { nMels, nMfcc });
   validateMelFrequencyRange('mfcc', fmin, fmax, sampleRate);
   return requireModule().mfcc(
     samples,
     sampleRate,
-    nFft,
-    hopLength,
+    fft.nFft,
+    fft.hopLength,
     nMels,
     nMfcc,
     fmin,
@@ -671,343 +621,6 @@ export function reassignedSpectrogram(
   );
 }
 
-// ============================================================================
-// Features - Inverse reconstruction
-// ============================================================================
-
-/**
- * Approximate inverse of a Mel filterbank: Mel power spectrogram -> STFT power
- * spectrogram. Mirrors `feature::mel_to_stft`.
- *
- * @param melPower - Mel power spectrogram [nMels x nFrames] row-major
- * @param nMels - Number of Mel bands
- * @param nFrames - Number of time frames
- * @param sampleRate - Sample rate in Hz
- * @param nFft - FFT size (default: 2048)
- * @param fmin - Lower Mel band edge in Hz (default: 0)
- * @param fmax - Upper Mel band edge in Hz (default: sr/2 when 0)
- * @param htk - Use the HTK Mel formula instead of Slaney (default: false)
- * @returns STFT power spectrogram result
- */
-export function melToStft(request: MelToStftRequest): StftPowerResult;
-export function melToStft(
-  melPower: Float32Array,
-  nMels: number,
-  nFrames: number,
-  sampleRate?: number,
-  nFft?: number,
-  fmin?: number,
-  fmax?: number,
-  htk?: boolean,
-  options?: GuardedOptions,
-): StftPowerResult;
-export function melToStft(
-  melPower: Float32Array | MelToStftRequest,
-  nMels = 0,
-  nFrames = 0,
-  sampleRate = 22050,
-  nFft = 2048,
-  fmin = 0,
-  fmax = 0,
-  htk = false,
-  options: GuardedOptions = {},
-): StftPowerResult {
-  if (!(melPower instanceof Float32Array)) {
-    const request = melPower;
-    return melToStft(
-      request.melPower,
-      request.nMels,
-      request.nFrames,
-      request.sampleRate,
-      request.nFft,
-      request.fmin,
-      request.fmax,
-      request.htk,
-      request,
-    );
-  }
-  assertSampleRate('melToStft', sampleRate);
-  validateMatrix('melToStft', melPower, nMels, nFrames, 'melPower', 'nMels', options);
-  validatePositiveIntegers('melToStft', { nFft });
-  validateMelFrequencyRange('melToStft', fmin, fmax, sampleRate);
-  return requireModule().melToStft(melPower, nMels, nFrames, sampleRate, nFft, fmin, fmax, htk);
-}
-
-/**
- * Reconstruct audio from a Mel power spectrogram via Griffin-Lim. Mirrors
- * `feature::mel_to_audio`.
- *
- * @param melPower - Mel power spectrogram [nMels x nFrames] row-major
- * @param nMels - Number of Mel bands
- * @param nFrames - Number of time frames
- * @param sampleRate - Sample rate in Hz
- * @param nFft - FFT size (default: 2048)
- * @param hopLength - Hop length (default: 512)
- * @param fmin - Minimum Mel frequency in Hz (default: 0)
- * @param fmax - Maximum Mel frequency in Hz (default: 0 = sr/2)
- * @param nIter - Griffin-Lim iterations (default: 32)
- * @param htk - Use the HTK Mel formula instead of Slaney (default: false)
- * @returns Reconstructed audio samples (mono, float32)
- */
-export function melToAudio(request: MelToAudioRequest): Float32Array;
-export function melToAudio(
-  melPower: Float32Array,
-  nMels: number,
-  nFrames: number,
-  sampleRate?: number,
-  nFft?: number,
-  hopLength?: number,
-  fmin?: number,
-  fmax?: number,
-  nIter?: number,
-  htk?: boolean,
-  options?: GuardedOptions,
-): Float32Array;
-export function melToAudio(
-  melPower: Float32Array | MelToAudioRequest,
-  nMels = 0,
-  nFrames = 0,
-  sampleRate = 22050,
-  nFft = 2048,
-  hopLength = 512,
-  fmin = 0,
-  fmax = 0,
-  nIter = 32,
-  htk = false,
-  options: GuardedOptions = {},
-): Float32Array {
-  if (!(melPower instanceof Float32Array)) {
-    const request = melPower;
-    return melToAudio(
-      request.melPower,
-      request.nMels,
-      request.nFrames,
-      request.sampleRate,
-      request.nFft,
-      request.hopLength,
-      request.fmin,
-      request.fmax,
-      request.nIter,
-      request.htk,
-      request,
-    );
-  }
-  assertSampleRate('melToAudio', sampleRate);
-  validateMatrix('melToAudio', melPower, nMels, nFrames, 'melPower', 'nMels', options);
-  validatePositiveIntegers('melToAudio', { nFft, hopLength, nIter });
-  validateMelFrequencyRange('melToAudio', fmin, fmax, sampleRate);
-  return requireModule().melToAudio(
-    melPower,
-    nMels,
-    nFrames,
-    sampleRate,
-    nFft,
-    hopLength,
-    fmin,
-    fmax,
-    nIter,
-    htk,
-  );
-}
-
-/** 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`.
- *
- * @param mfccCoefficients - MFCC matrix [nMfcc x nFrames] row-major
- * @param nMfcc - Number of MFCC coefficients
- * @param nFrames - Number of time frames
- * @param nMels - Number of Mel bins to reconstruct (default: 128)
- * @returns Mel power spectrogram result
- */
-export function mfccToMel(request: MfccToMelRequest): MelPowerResult;
-export function mfccToMel(
-  mfccCoefficients: Float32Array,
-  nMfcc: number,
-  nFrames: number,
-  nMels?: number,
-  lifter?: number,
-  options?: GuardedOptions,
-): MelPowerResult;
-export function mfccToMel(
-  mfccCoefficients: Float32Array | MfccToMelRequest,
-  nMfcc = 0,
-  nFrames = 0,
-  nMels = 128,
-  lifter = 0,
-  options: GuardedOptions = {},
-): MelPowerResult {
-  if (!(mfccCoefficients instanceof Float32Array)) {
-    const request = mfccCoefficients;
-    return mfccToMel(
-      request.mfccCoefficients,
-      request.nMfcc,
-      request.nFrames,
-      request.nMels,
-      request.lifter,
-      request,
-    );
-  }
-  validateMatrix(
-    'mfccToMel',
-    mfccCoefficients,
-    nMfcc,
-    nFrames,
-    'mfccCoefficients',
-    'nMfcc',
-    options,
-  );
-  validatePositiveIntegers('mfccToMel', { nMels });
-  return requireModule().mfccToMel(mfccCoefficients, nMfcc, nFrames, nMels, lifter);
-}
-
-/**
- * Reconstruct audio directly from MFCC coefficients via Griffin-Lim. Mirrors
- * `feature::mfcc_to_audio`.
- *
- * @param mfccCoefficients - MFCC matrix [nMfcc x nFrames] row-major
- * @param nMfcc - Number of MFCC coefficients
- * @param nFrames - Number of time frames
- * @param nMels - Number of Mel bins (default: 128)
- * @param sampleRate - Sample rate in Hz (default: 22050)
- * @param nFft - FFT size (default: 2048)
- * @param hopLength - Hop length (default: 512)
- * @param fmin - Minimum Mel frequency in Hz (default: 0)
- * @param fmax - Maximum Mel frequency in Hz (default: 0 = sr/2)
- * @param nIter - Griffin-Lim iterations (default: 32)
- * @param htk - Use the HTK Mel formula instead of Slaney (default: false)
- * @returns Reconstructed audio samples (mono, float32)
- */
-export function mfccToAudio(request: MfccToAudioRequest): Float32Array;
-export function mfccToAudio(
-  mfccCoefficients: Float32Array,
-  nMfcc: number,
-  nFrames: number,
-  nMels?: number,
-  sampleRate?: number,
-  nFft?: number,
-  hopLength?: number,
-  fmin?: number,
-  fmax?: number,
-  nIter?: number,
-  htk?: boolean,
-  lifter?: number,
-  options?: GuardedOptions,
-): Float32Array;
-export function mfccToAudio(
-  mfccCoefficients: Float32Array | MfccToAudioRequest,
-  nMfcc = 0,
-  nFrames = 0,
-  nMels = 128,
-  sampleRate = 22050,
-  nFft = 2048,
-  hopLength = 512,
-  fmin = 0,
-  fmax = 0,
-  nIter = 32,
-  htk = false,
-  lifter = 0,
-  options: GuardedOptions = {},
-): Float32Array {
-  if (!(mfccCoefficients instanceof Float32Array)) {
-    const request = mfccCoefficients;
-    return mfccToAudio(
-      request.mfccCoefficients,
-      request.nMfcc,
-      request.nFrames,
-      request.nMels,
-      request.sampleRate,
-      request.nFft,
-      request.hopLength,
-      request.fmin,
-      request.fmax,
-      request.nIter,
-      request.htk,
-      request.lifter,
-      request,
-    );
-  }
-  assertSampleRate('mfccToAudio', sampleRate);
-  validateMatrix(
-    'mfccToAudio',
-    mfccCoefficients,
-    nMfcc,
-    nFrames,
-    'mfccCoefficients',
-    'nMfcc',
-    options,
-  );
-  validatePositiveIntegers('mfccToAudio', { nMels, nFft, hopLength, nIter });
-  validateMelFrequencyRange('mfccToAudio', fmin, fmax, sampleRate);
-  return requireModule().mfccToAudio(
-    mfccCoefficients,
-    nMfcc,
-    nFrames,
-    nMels,
-    sampleRate,
-    nFft,
-    hopLength,
-    fmin,
-    fmax,
-    nIter,
-    htk,
-    lifter,
-  );
-}
-
 // ============================================================================
 // Features - Chroma
 // ============================================================================
@@ -1017,9 +630,9 @@ export function mfccToAudio(
  *
  * The chroma filterbank uses a fixed tuning of 0 (concert A440). Unlike
  * librosa.feature.chroma_stft — which estimates tuning from the signal when none
- * is given — this does NOT auto-estimate and exposes no tuning argument, so
- * sharp/flat (non-A440) recordings smear across pitch classes. Estimate tuning
- * separately via {@link estimateTuning} if a non-A440 reference matters.
+ * is given — this does NOT auto-estimate and takes no tuning argument. A
+ * tuning offset from {@link estimateTuning} is applied through `analyze`'s
+ * `tuning` option (and to chords through `detectChords`).
  *
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz (default: 22050)
@@ -1047,6 +660,6 @@ export function chroma(
     return chroma(request.samples, request.sampleRate, request.nFft, request.hopLength, request);
   }
   validateSpectrogramSamples('chroma', samples, sampleRate, options);
-  validatePositiveIntegers('chroma', { nFft, hopLength });
-  return requireModule().chroma(samples, sampleRate, nFft, hopLength);
+  const fft = resolveFftOptions('chroma', nFft, hopLength);
+  return requireModule().chroma(samples, sampleRate, fft.nFft, fft.hopLength);
 }