@libraz/libsonare 1.2.3 → 1.3.0

package/src/feature_core.ts

@@ -0,0 +1,248 @@
+import { getSonareModule } from './module_state';
+import type { TempogramMode } from './public_types';
+import type {
+  WasmCyclicTempogramResult,
+  WasmFrameResult,
+  WasmTempogramResult,
+  WasmTrimResult,
+} from './sonare.js';
+
+function requireModule() {
+  return getSonareModule();
+}
+
+// ============================================================================
+// Core - Unit Conversion
+// ============================================================================
+
+/**
+ * Convert frequency in Hz to Mel scale.
+ *
+ * @param hz - Frequency in Hz
+ * @returns Mel frequency
+ */
+export function hzToMel(hz: number): number {
+  return requireModule().hzToMel(hz);
+}
+
+/**
+ * Convert Mel scale to frequency in Hz.
+ *
+ * @param mel - Mel frequency
+ * @returns Frequency in Hz
+ */
+export function melToHz(mel: number): number {
+  return requireModule().melToHz(mel);
+}
+
+/**
+ * Convert frequency in Hz to MIDI note number.
+ *
+ * @param hz - Frequency in Hz
+ * @returns MIDI note number (A4 = 440 Hz = 69)
+ */
+export function hzToMidi(hz: number): number {
+  return requireModule().hzToMidi(hz);
+}
+
+/**
+ * Convert MIDI note number to frequency in Hz.
+ *
+ * @param midi - MIDI note number
+ * @returns Frequency in Hz
+ */
+export function midiToHz(midi: number): number {
+  return requireModule().midiToHz(midi);
+}
+
+/**
+ * Convert frequency in Hz to note name.
+ *
+ * @param hz - Frequency in Hz
+ * @returns Note name (e.g., "A4", "C#5")
+ */
+export function hzToNote(hz: number): string {
+  return requireModule().hzToNote(hz);
+}
+
+/**
+ * Convert note name to frequency in Hz.
+ *
+ * @param note - Note name (e.g., "A4", "C#5")
+ * @returns Frequency in Hz
+ */
+export function noteToHz(note: string): number {
+  return requireModule().noteToHz(note);
+}
+
+/**
+ * Convert frame index to time in seconds.
+ *
+ * @param frames - Frame index
+ * @param sr - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length in samples (default: 512)
+ * @returns Time in seconds
+ */
+export function framesToTime(frames: number, sr = 22050, hopLength = 512): number {
+  return requireModule().framesToTime(frames, sr, hopLength);
+}
+
+/**
+ * Convert time in seconds to frame index.
+ *
+ * @param time - Time in seconds
+ * @param sr - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length in samples (default: 512)
+ * @returns Frame index
+ */
+export function timeToFrames(time: number, sr = 22050, hopLength = 512): number {
+  return requireModule().timeToFrames(time, sr, hopLength);
+}
+
+export function framesToSamples(frames: number, hopLength = 512, nFft = 0): number {
+  return requireModule().framesToSamples(frames, hopLength, nFft);
+}
+
+export function samplesToFrames(samples: number, hopLength = 512, nFft = 0): number {
+  return requireModule().samplesToFrames(samples, hopLength, nFft);
+}
+
+export function powerToDb(
+  values: Float32Array,
+  ref = 1.0,
+  amin = 1e-10,
+  topDb = 80.0,
+): Float32Array {
+  return requireModule().powerToDb(values, ref, amin, topDb);
+}
+
+export function amplitudeToDb(
+  values: Float32Array,
+  ref = 1.0,
+  amin = 1e-5,
+  topDb = 80.0,
+): Float32Array {
+  return requireModule().amplitudeToDb(values, ref, amin, topDb);
+}
+
+export function dbToPower(values: Float32Array, ref = 1.0): Float32Array {
+  return requireModule().dbToPower(values, ref);
+}
+
+export function dbToAmplitude(values: Float32Array, ref = 1.0): Float32Array {
+  return requireModule().dbToAmplitude(values, ref);
+}
+
+export function preemphasis(samples: Float32Array, coef = 0.97, zi?: number): Float32Array {
+  return requireModule().preemphasis(samples, coef, zi ?? null);
+}
+
+export function deemphasis(samples: Float32Array, coef = 0.97, zi?: number): Float32Array {
+  return requireModule().deemphasis(samples, coef, zi ?? null);
+}
+
+export function trimSilence(
+  samples: Float32Array,
+  topDb = 60.0,
+  frameLength = 2048,
+  hopLength = 512,
+): WasmTrimResult {
+  return requireModule().trimSilence(samples, topDb, frameLength, hopLength);
+}
+
+export function splitSilence(
+  samples: Float32Array,
+  topDb = 60.0,
+  frameLength = 2048,
+  hopLength = 512,
+): Int32Array {
+  return requireModule().splitSilence(samples, topDb, frameLength, hopLength);
+}
+
+export function frameSignal(
+  samples: Float32Array,
+  frameLength: number,
+  hopLength: number,
+): WasmFrameResult {
+  return requireModule().frameSignal(samples, frameLength, hopLength);
+}
+
+export function padCenter(values: Float32Array, targetSize: number, padValue = 0.0): Float32Array {
+  return requireModule().padCenter(values, targetSize, padValue);
+}
+
+export function fixLength(values: Float32Array, targetSize: number, padValue = 0.0): Float32Array {
+  return requireModule().fixLength(values, targetSize, padValue);
+}
+
+export function fixFrames(frames: Int32Array, xMin = 0, xMax = -1, pad = true): Int32Array {
+  return requireModule().fixFrames(frames, xMin, xMax, pad);
+}
+
+export function peakPick(
+  values: Float32Array,
+  preMax: number,
+  postMax: number,
+  preAvg: number,
+  postAvg: number,
+  delta: number,
+  wait: number,
+): Int32Array {
+  return requireModule().peakPick(values, preMax, postMax, preAvg, postAvg, delta, wait);
+}
+
+export function vectorNormalize(values: Float32Array, normType = 0, threshold = 0.0): Float32Array {
+  return requireModule().vectorNormalize(values, normType, threshold);
+}
+
+export function pcen(
+  values: Float32Array,
+  nBins: number,
+  nFrames: number,
+  options: Record<string, number> = {},
+): Float32Array {
+  return requireModule().pcen(values, nBins, nFrames, options);
+}
+
+export function tonnetz(chromagram: Float32Array, nChroma: number, nFrames: number): Float32Array {
+  return requireModule().tonnetz(chromagram, nChroma, nFrames);
+}
+
+export function tempogram(
+  onsetEnvelope: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  winLength = 384,
+  mode: TempogramMode = 'autocorrelation',
+): WasmTempogramResult {
+  return requireModule().tempogram(onsetEnvelope, sampleRate, hopLength, winLength, mode);
+}
+
+export function cyclicTempogram(
+  onsetEnvelope: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  winLength = 384,
+  bpmMin = 60.0,
+  nBins = 60,
+): WasmCyclicTempogramResult {
+  return requireModule().cyclicTempogram(
+    onsetEnvelope,
+    sampleRate,
+    hopLength,
+    winLength,
+    bpmMin,
+    nBins,
+  );
+}
+
+export function plp(
+  onsetEnvelope: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  tempoMin = 30.0,
+  tempoMax = 300.0,
+  winLength = 384,
+): Float32Array {
+  return requireModule().plp(onsetEnvelope, sampleRate, hopLength, tempoMin, tempoMax, winLength);
+}

package/src/feature_music.ts

@@ -0,0 +1,419 @@
+import { getSonareModule } from './module_state';
+import type {
+  AnalyzeSectionsOptions,
+  CqtResult,
+  LufsResult,
+  MelodyResult,
+  OnsetStrengthMultiResult,
+  Section,
+  SectionType,
+} from './public_types';
+import type { WasmFourierTempogramResult, WasmNnlsChromaResult } from './sonare.js';
+import type { ValidateOptions } from './validation';
+import {
+  assertFiniteScalar,
+  assertPositiveInteger,
+  assertSampleRate,
+  assertSamples,
+} from './validation';
+
+function requireModule() {
+  return getSonareModule();
+}
+
+type GuardedOptions = ValidateOptions;
+type AnalyzeSectionsGuardedOptions = AnalyzeSectionsOptions & ValidateOptions;
+type MelodyGuardedOptions = MelodyOptions & ValidateOptions;
+
+function validateMusicSamples(
+  fnName: string,
+  samples: Float32Array,
+  sampleRate: number,
+  options: GuardedOptions = {},
+): void {
+  assertSampleRate(fnName, sampleRate);
+  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 validateFrequencyBounds(fnName: string, fmin: number, fmax?: number): void {
+  assertFiniteScalar(fnName, fmin, 'fmin');
+  if (fmin < 0) {
+    throw new RangeError(`${fnName}: fmin must be non-negative`);
+  }
+  if (fmax !== undefined) {
+    assertFiniteScalar(fnName, fmax, 'fmax');
+    if (fmax <= fmin) {
+      throw new RangeError(`${fnName}: fmax must be greater than fmin`);
+    }
+  }
+}
+
+/**
+ * Compute NNLS (non-negative least squares) chromagram.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @returns NNLS chroma result
+ */
+export function nnlsChroma(
+  samples: Float32Array,
+  sampleRate = 22050,
+  options: GuardedOptions = {},
+): WasmNnlsChromaResult {
+  validateMusicSamples('nnlsChroma', samples, sampleRate, options);
+  return requireModule().nnlsChroma(samples, sampleRate);
+}
+
+/**
+ * Compute the Constant-Q Transform magnitude.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length (default: 512)
+ * @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)
+ * @returns CQT magnitude result
+ */
+export function cqt(
+  samples: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  fmin = 32.70319566257483,
+  nBins = 84,
+  binsPerOctave = 12,
+  options: GuardedOptions = {},
+): CqtResult {
+  validateMusicSamples('cqt', samples, sampleRate, options);
+  validatePositiveIntegers('cqt', { hopLength, nBins, binsPerOctave });
+  validateFrequencyBounds('cqt', fmin);
+  return requireModule().cqt(samples, sampleRate, hopLength, fmin, nBins, binsPerOctave);
+}
+
+/**
+ * Compute the pseudo Constant-Q Transform magnitude.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length (default: 512)
+ * @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)
+ * @returns CQT magnitude result
+ */
+export function pseudoCqt(
+  samples: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  fmin = 32.70319566257483,
+  nBins = 84,
+  binsPerOctave = 12,
+  options: GuardedOptions = {},
+): CqtResult {
+  validateMusicSamples('pseudoCqt', samples, sampleRate, options);
+  validatePositiveIntegers('pseudoCqt', { hopLength, nBins, binsPerOctave });
+  validateFrequencyBounds('pseudoCqt', fmin);
+  return requireModule().pseudoCqt(samples, sampleRate, hopLength, fmin, nBins, binsPerOctave);
+}
+
+/**
+ * Compute the hybrid Constant-Q Transform magnitude.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length (default: 512)
+ * @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)
+ * @returns CQT magnitude result
+ */
+export function hybridCqt(
+  samples: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  fmin = 32.70319566257483,
+  nBins = 84,
+  binsPerOctave = 12,
+  options: GuardedOptions = {},
+): CqtResult {
+  validateMusicSamples('hybridCqt', samples, sampleRate, options);
+  validatePositiveIntegers('hybridCqt', { hopLength, nBins, binsPerOctave });
+  validateFrequencyBounds('hybridCqt', fmin);
+  return requireModule().hybridCqt(samples, sampleRate, hopLength, fmin, nBins, binsPerOctave);
+}
+
+/**
+ * Compute the Variable-Q Transform magnitude (gamma controls Q).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length (default: 512)
+ * @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)
+ * @returns VQT magnitude result (same shape as CQT)
+ */
+export function vqt(
+  samples: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  fmin = 32.70319566257483,
+  nBins = 84,
+  binsPerOctave = 12,
+  gamma = 0,
+  options: GuardedOptions = {},
+): CqtResult {
+  validateMusicSamples('vqt', samples, sampleRate, options);
+  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);
+}
+
+/**
+ * Detect song-structure sections (intro/verse/chorus/...).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param nFft - FFT size (default: 2048)
+ * @param hopLength - Hop length (default: 512)
+ * @param minSectionSec - Minimum section duration in seconds (default: 4.0)
+ * @returns Array of detected sections
+ */
+export function analyzeSections(
+  samples: Float32Array,
+  sampleRate = 22050,
+  options: AnalyzeSectionsGuardedOptions = {},
+): Section[] {
+  validateMusicSamples('analyzeSections', samples, sampleRate, options);
+  validatePositiveIntegers('analyzeSections', {
+    nFft: options.nFft ?? 2048,
+    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');
+  }
+  return requireModule()
+    .analyzeSections(
+      samples,
+      sampleRate,
+      options.nFft ?? 2048,
+      options.hopLength ?? 512,
+      options.minSectionSec ?? 4.0,
+    )
+    .map((s) => ({ ...s, type: s.type as SectionType }));
+}
+
+/** Options for {@link analyzeMelody}. All fields are optional. */
+export interface MelodyOptions {
+  /** Lowest f0 (Hz) the tracker will consider. Default 65 (≈ C2). */
+  fmin?: number;
+  /** Highest f0 (Hz) the tracker will consider. Default 2093 (≈ C7). */
+  fmax?: number;
+  /** Analysis frame length in samples. Default 2048. */
+  frameLength?: number;
+  /** Hop length between frames in samples. Default 256. */
+  hopLength?: number;
+  /** Voicing confidence threshold in [0,1]; frames below are unvoiced. Default 0.1. */
+  threshold?: number;
+  /**
+   * Use the pYIN tracker (Viterbi-smoothed) instead of plain per-frame YIN.
+   * Produces a less octave-jumpy contour. Defaults to `false`.
+   */
+  usePyin?: boolean;
+  /**
+   * When {@link usePyin} is `true`, reflect-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`.
+   */
+  center?: boolean;
+}
+
+/**
+ * Extract the melody contour from monophonic audio via YIN (or pYIN).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param options - Tracker + tuning options ({@link MelodyOptions})
+ * @returns Melody contour with per-frame pitch points and summary stats
+ */
+export function analyzeMelody(
+  samples: Float32Array,
+  sampleRate = 22050,
+  options: MelodyGuardedOptions = {},
+): MelodyResult {
+  validateMusicSamples('analyzeMelody', samples, sampleRate, options);
+  const fmin = options.fmin ?? 65.0;
+  const fmax = options.fmax ?? 2093.0;
+  validateFrequencyBounds('analyzeMelody', fmin, fmax);
+  validatePositiveIntegers('analyzeMelody', {
+    frameLength: options.frameLength ?? 2048,
+    hopLength: options.hopLength ?? 256,
+  });
+  assertFiniteScalar('analyzeMelody', options.threshold ?? 0.1, 'threshold');
+  return requireModule().analyzeMelody(
+    samples,
+    sampleRate,
+    options.fmin ?? 65.0,
+    options.fmax ?? 2093.0,
+    options.frameLength ?? 2048,
+    options.hopLength ?? 256,
+    options.threshold ?? 0.1,
+    options.usePyin ?? false,
+    options.center ?? true,
+  );
+}
+
+/**
+ * Compute the onset strength envelope.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param nFft - FFT size (default: 2048)
+ * @param hopLength - Hop length (default: 512)
+ * @param nMels - Number of Mel bands (default: 128)
+ * @returns Onset envelope for each frame
+ */
+export function onsetEnvelope(
+  samples: Float32Array,
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  nMels = 128,
+  options: GuardedOptions = {},
+): Float32Array {
+  validateMusicSamples('onsetEnvelope', samples, sampleRate, options);
+  validatePositiveIntegers('onsetEnvelope', { nFft, hopLength, nMels });
+  return requireModule().onsetEnvelope(samples, sampleRate, nFft, hopLength, nMels);
+}
+
+/**
+ * Compute multi-band onset strength envelopes.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param nFft - FFT size (default: 2048)
+ * @param hopLength - Hop length (default: 512)
+ * @param nMels - Number of Mel bands (default: 128)
+ * @param nBands - Number of onset bands (default: 3)
+ * @returns Multi-band onset matrix
+ */
+export function onsetStrengthMulti(
+  samples: Float32Array,
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  nMels = 128,
+  nBands = 3,
+  options: GuardedOptions = {},
+): OnsetStrengthMultiResult {
+  validateMusicSamples('onsetStrengthMulti', samples, sampleRate, options);
+  validatePositiveIntegers('onsetStrengthMulti', { nFft, hopLength, nMels, nBands });
+  return requireModule().onsetStrengthMulti(samples, sampleRate, nFft, hopLength, nMels, nBands);
+}
+
+/**
+ * Compute the Fourier tempogram from an onset envelope.
+ *
+ * @param onsetEnvelope - Onset strength envelope (float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length (default: 512)
+ * @param winLength - Window length in frames (default: 384)
+ * @returns Fourier tempogram result
+ */
+export function fourierTempogram(
+  onsetEnvelope: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  winLength = 384,
+  options: GuardedOptions = {},
+): WasmFourierTempogramResult {
+  assertSampleRate('fourierTempogram', sampleRate);
+  assertSamples('fourierTempogram', onsetEnvelope, options.validate !== false, 'onsetEnvelope');
+  validatePositiveIntegers('fourierTempogram', { hopLength, winLength });
+  return requireModule().fourierTempogram(onsetEnvelope, sampleRate, hopLength, winLength);
+}
+
+/**
+ * Compute tempogram ratio features.
+ *
+ * @param tempogramData - Tempogram data (float32)
+ * @param winLength - Window length in frames (default: 384)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length (default: 512)
+ * @returns Tempogram ratio features
+ */
+export function tempogramRatio(
+  tempogramData: Float32Array,
+  winLength = 384,
+  sampleRate = 22050,
+  hopLength = 512,
+  options: GuardedOptions = {},
+): Float32Array {
+  assertSampleRate('tempogramRatio', sampleRate);
+  assertSamples('tempogramRatio', tempogramData, options.validate !== false, 'tempogramData');
+  validatePositiveIntegers('tempogramRatio', { winLength, hopLength });
+  return requireModule().tempogramRatio(tempogramData, winLength, sampleRate, hopLength);
+}
+
+/**
+ * Measure loudness (EBU R128 / ITU-R BS.1770).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @returns Loudness measurement result
+ */
+export function lufs(
+  samples: Float32Array,
+  sampleRate = 22050,
+  options: ValidateOptions = {},
+): LufsResult {
+  assertSampleRate('lufs', sampleRate);
+  assertSamples('lufs', samples, options.validate !== false);
+  return requireModule().lufs(samples, sampleRate);
+}
+
+/**
+ * Compute the momentary loudness (LUFS) over time.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @returns Momentary LUFS values over time
+ */
+export function momentaryLufs(
+  samples: Float32Array,
+  sampleRate = 22050,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSampleRate('momentaryLufs', sampleRate);
+  assertSamples('momentaryLufs', samples, options.validate !== false);
+  return requireModule().momentaryLufs(samples, sampleRate);
+}
+
+/**
+ * Compute the short-term loudness (LUFS) over time.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @returns Short-term LUFS values over time
+ */
+export function shortTermLufs(
+  samples: Float32Array,
+  sampleRate = 22050,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSampleRate('shortTermLufs', sampleRate);
+  assertSamples('shortTermLufs', samples, options.validate !== false);
+  return requireModule().shortTermLufs(samples, sampleRate);
+}