@libraz/libsonare 1.5.2 → 1.5.3

package/src/feature_spectrogram.ts

@@ -21,6 +21,75 @@ function requireModule() {
 
 type GuardedOptions = ValidateOptions;
 
+/** Canonical request form for basic frame-based spectrogram features. */
+export interface SpectrogramRequest extends GuardedOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+  nFft?: number;
+  hopLength?: number;
+}
+
+export interface ChromaSpectrogramRequest extends GuardedOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+  hopLength?: number;
+  nChroma?: number;
+}
+
+export interface MelSpectrogramRequest extends SpectrogramRequest {
+  nMels?: number;
+  fmin?: number;
+  fmax?: number;
+  htk?: boolean;
+}
+
+export interface MfccRequest extends MelSpectrogramRequest {
+  nMfcc?: number;
+  lifter?: number;
+}
+
+export interface MfccToMelRequest extends GuardedOptions {
+  mfccCoefficients: Float32Array;
+  nMfcc: number;
+  nFrames: number;
+  nMels?: 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;
+}
+
+/** 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;
+  thresholdDb?: number;
+}
+
 function validateSpectrogramSamples(
   fnName: string,
   samples: Float32Array,
@@ -82,12 +151,23 @@ function validateMatrix(
  * @param thresholdDb - Silence threshold in dB (default: -60 dB)
  * @returns Trimmed audio
  */
+export function trim(request: TrimRequest): Float32Array;
 export function trim(
   samples: Float32Array,
   sampleRate: number,
+  thresholdDb?: number,
+  options?: GuardedOptions,
+): Float32Array;
+export function trim(
+  samples: Float32Array | TrimRequest,
+  sampleRate = 22050,
   thresholdDb = -60.0,
   options: GuardedOptions = {},
 ): Float32Array {
+  if (!(samples instanceof Float32Array)) {
+    const r = samples;
+    return trim(r.samples, r.sampleRate, r.thresholdDb, r);
+  }
   validateSpectrogramSamples('trim', samples, sampleRate, options);
   assertFiniteScalar('trim', thresholdDb, 'thresholdDb');
   return requireModule().trim(samples, sampleRate, thresholdDb);
@@ -106,13 +186,25 @@ export function trim(
  * @param hopLength - Hop length (default: 512)
  * @returns STFT result with magnitude and power spectrograms
  */
+export function stft(request: SpectrogramRequest): StftResult;
 export function stft(
   samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: GuardedOptions,
+): StftResult;
+export function stft(
+  samples: Float32Array | SpectrogramRequest,
   sampleRate = 22050,
   nFft = 2048,
   hopLength = 512,
   options: GuardedOptions = {},
 ): StftResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    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);
@@ -127,13 +219,29 @@ export function stft(
  * @param hopLength - Hop length (default: 512)
  * @returns STFT result with dB values
  */
+export function stftDb(request: SpectrogramRequest): {
+  nBins: number;
+  nFrames: number;
+  db: Float32Array;
+};
 export function stftDb(
   samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: GuardedOptions,
+): { nBins: number; nFrames: number; db: Float32Array };
+export function stftDb(
+  samples: Float32Array | SpectrogramRequest,
   sampleRate = 22050,
   nFft = 2048,
   hopLength = 512,
   options: GuardedOptions = {},
 ): { nBins: number; nFrames: number; db: Float32Array } {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    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);
@@ -148,13 +256,31 @@ export function stftDb(
  * @param nChroma - Number of chroma bins (default: 12)
  * @returns Chroma result
  */
+export function chromaCens(request: ChromaSpectrogramRequest): ChromaResult;
 export function chromaCens(
   samples: Float32Array,
+  sampleRate?: number,
+  hopLength?: number,
+  nChroma?: number,
+  options?: GuardedOptions,
+): ChromaResult;
+export function chromaCens(
+  samples: Float32Array | ChromaSpectrogramRequest,
   sampleRate = 22050,
   hopLength = 512,
   nChroma = 12,
   options: GuardedOptions = {},
 ): ChromaResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    return chromaCens(
+      request.samples,
+      request.sampleRate,
+      request.hopLength,
+      request.nChroma,
+      request,
+    );
+  }
   validateSpectrogramSamples('chromaCens', samples, sampleRate, options);
   validatePositiveIntegers('chromaCens', { hopLength, nChroma });
   return requireModule().chromaCens(samples, sampleRate, hopLength, nChroma);
@@ -169,13 +295,31 @@ export function chromaCens(
  * @param nChroma - Number of chroma bins (default: 12)
  * @returns Chroma result
  */
+export function chromaCqt(request: ChromaSpectrogramRequest): ChromaResult;
 export function chromaCqt(
   samples: Float32Array,
+  sampleRate?: number,
+  hopLength?: number,
+  nChroma?: number,
+  options?: GuardedOptions,
+): ChromaResult;
+export function chromaCqt(
+  samples: Float32Array | ChromaSpectrogramRequest,
   sampleRate = 22050,
   hopLength = 512,
   nChroma = 12,
   options: GuardedOptions = {},
 ): ChromaResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    return chromaCqt(
+      request.samples,
+      request.sampleRate,
+      request.hopLength,
+      request.nChroma,
+      request,
+    );
+  }
   validateSpectrogramSamples('chromaCqt', samples, sampleRate, options);
   validatePositiveIntegers('chromaCqt', { hopLength, nChroma });
   return requireModule().chromaCqt(samples, sampleRate, hopLength, nChroma);
@@ -190,13 +334,31 @@ export function chromaCqt(
  * @param nChroma - Number of chroma bins (default: 12)
  * @returns Chroma result
  */
+export function bassChroma(request: ChromaSpectrogramRequest): ChromaResult;
 export function bassChroma(
   samples: Float32Array,
+  sampleRate?: number,
+  hopLength?: number,
+  nChroma?: number,
+  options?: GuardedOptions,
+): ChromaResult;
+export function bassChroma(
+  samples: Float32Array | ChromaSpectrogramRequest,
   sampleRate = 22050,
   hopLength = 512,
   nChroma = 12,
   options: GuardedOptions = {},
 ): ChromaResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    return bassChroma(
+      request.samples,
+      request.sampleRate,
+      request.hopLength,
+      request.nChroma,
+      request,
+    );
+  }
   validateSpectrogramSamples('bassChroma', samples, sampleRate, options);
   validatePositiveIntegers('bassChroma', { hopLength, nChroma });
   return requireModule().bassChroma(samples, sampleRate, hopLength, nChroma);
@@ -220,8 +382,20 @@ export function bassChroma(
  * @param htk - Use the HTK Mel formula instead of Slaney (default: false)
  * @returns Mel spectrogram result
  */
+export function melSpectrogram(request: MelSpectrogramRequest): MelSpectrogramResult;
 export function melSpectrogram(
   samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  nMels?: number,
+  fmin?: number,
+  fmax?: number,
+  htk?: boolean,
+  options?: GuardedOptions,
+): MelSpectrogramResult;
+export function melSpectrogram(
+  samples: Float32Array | MelSpectrogramRequest,
   sampleRate = 22050,
   nFft = 2048,
   hopLength = 512,
@@ -231,6 +405,20 @@ export function melSpectrogram(
   htk = false,
   options: GuardedOptions = {},
 ): MelSpectrogramResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    return melSpectrogram(
+      request.samples,
+      request.sampleRate,
+      request.nFft,
+      request.hopLength,
+      request.nMels,
+      request.fmin,
+      request.fmax,
+      request.htk,
+      request,
+    );
+  }
   validateSpectrogramSamples('melSpectrogram', samples, sampleRate, options);
   validatePositiveIntegers('melSpectrogram', { nFft, hopLength, nMels });
   validateMelFrequencyRange('melSpectrogram', fmin, fmax, sampleRate);
@@ -261,8 +449,22 @@ export function melSpectrogram(
  * @param lifter - Cepstral liftering coefficient (default: 0 = no liftering)
  * @returns MFCC result
  */
+export function mfcc(request: MfccRequest): MfccResult;
 export function mfcc(
   samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  nMels?: number,
+  nMfcc?: number,
+  fmin?: number,
+  fmax?: number,
+  htk?: boolean,
+  lifter?: number,
+  options?: GuardedOptions,
+): MfccResult;
+export function mfcc(
+  samples: Float32Array | MfccRequest,
   sampleRate = 22050,
   nFft = 2048,
   hopLength = 512,
@@ -274,6 +476,22 @@ export function mfcc(
   lifter = 0,
   options: GuardedOptions = {},
 ): MfccResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    return mfcc(
+      request.samples,
+      request.sampleRate,
+      request.nFft,
+      request.hopLength,
+      request.nMels,
+      request.nMfcc,
+      request.fmin,
+      request.fmax,
+      request.htk,
+      request.lifter,
+      request,
+    );
+  }
   validateSpectrogramSamples('mfcc', samples, sampleRate, options);
   validatePositiveIntegers('mfcc', { nFft, hopLength, nMels, nMfcc });
   validateMelFrequencyRange('mfcc', fmin, fmax, sampleRate);
@@ -309,10 +527,22 @@ export function mfcc(
  * @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,
@@ -320,6 +550,20 @@ export function melToStft(
   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 });
@@ -343,10 +587,24 @@ export function melToStft(
  * @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,
@@ -356,6 +614,22 @@ export function melToAudio(
   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 });
@@ -384,13 +658,31 @@ export function melToAudio(
  * @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,
+  options?: GuardedOptions,
+): MelPowerResult;
+export function mfccToMel(
+  mfccCoefficients: Float32Array | MfccToMelRequest,
+  nMfcc = 0,
+  nFrames = 0,
   nMels = 128,
   options: GuardedOptions = {},
 ): MelPowerResult {
+  if (!(mfccCoefficients instanceof Float32Array)) {
+    const request = mfccCoefficients;
+    return mfccToMel(
+      request.mfccCoefficients,
+      request.nMfcc,
+      request.nFrames,
+      request.nMels,
+      request,
+    );
+  }
   validateMatrix(
     'mfccToMel',
     mfccCoefficients,
@@ -421,10 +713,25 @@ export function mfccToMel(
  * @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,
+  options?: GuardedOptions,
+): Float32Array;
+export function mfccToAudio(
+  mfccCoefficients: Float32Array | MfccToAudioRequest,
+  nMfcc = 0,
+  nFrames = 0,
   nMels = 128,
   sampleRate = 22050,
   nFft = 2048,
@@ -435,6 +742,23 @@ export function mfccToAudio(
   htk = false,
   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,
+    );
+  }
   assertSampleRate('mfccToAudio', sampleRate);
   validateMatrix(
     'mfccToAudio',
@@ -481,13 +805,25 @@ export function mfccToAudio(
  * @param hopLength - Hop length (default: 512)
  * @returns Chroma features result
  */
+export function chroma(request: SpectrogramRequest): ChromaResult;
 export function chroma(
   samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: GuardedOptions,
+): ChromaResult;
+export function chroma(
+  samples: Float32Array | SpectrogramRequest,
   sampleRate = 22050,
   nFft = 2048,
   hopLength = 512,
   options: GuardedOptions = {},
 ): ChromaResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    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);