@libraz/libsonare 1.7.1 → 1.8.0

package/src/feature_music.ts

@@ -1,7 +1,11 @@
+import { validatePositiveIntegers } from './_feature_validation';
+import { resolveFftOptions } from './_fft_options';
 import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type {
   AnalyzeSectionsOptions,
+  BoundaryOptions,
+  BoundaryResult,
   CqtResult,
   LufsResult,
   MelodyResult,
@@ -16,6 +20,7 @@ import {
   assertPositiveInteger,
   assertSampleRate,
   assertSamples,
+  assertVqtGamma,
 } from './validation';
 
 function requireModule() {
@@ -24,6 +29,7 @@ function requireModule() {
 
 type GuardedOptions = ValidateOptions;
 type AnalyzeSectionsGuardedOptions = AnalyzeSectionsOptions & ValidateOptions;
+type BoundaryGuardedOptions = BoundaryOptions & ValidateOptions;
 type MelodyGuardedOptions = MelodyOptions & ValidateOptions;
 
 /** Canonical request form shared by the Constant-Q transform variants. */
@@ -89,6 +95,11 @@ export interface AnalyzeSectionsRequest extends AnalyzeSectionsGuardedOptions {
   samples: Float32Array;
   sampleRate?: number;
 }
+/** Canonical (and only) call form for {@link detectBoundaries}. */
+export interface DetectBoundariesRequest extends BoundaryGuardedOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+}
 export interface AnalyzeMelodyRequest extends MelodyGuardedOptions {
   samples: Float32Array;
   sampleRate?: number;
@@ -116,12 +127,6 @@ function validateMusicSamples(
   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) {
@@ -325,8 +330,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; negative selects the automatic ERB-derived
- *   value, while 0 is equivalent to CQT (default: -1)
+ * @param gamma - Bandwidth offset; a negative value or NaN 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;
@@ -366,7 +371,7 @@ export function vqt(
   validateMusicSamples('vqt', samples, sampleRate, options);
   validatePositiveIntegers('vqt', { hopLength, nBins, binsPerOctave });
   validateFrequencyBounds('vqt', fmin);
-  assertFiniteScalar('vqt', gamma, 'gamma');
+  assertVqtGamma('vqt', gamma);
   return requireModule().vqt(samples, sampleRate, hopLength, fmin, nBins, binsPerOctave, gamma);
 }
 
@@ -512,7 +517,7 @@ export function vqtToAudio(
     nIter,
     options,
   );
-  assertFiniteScalar('vqtToAudio', gamma, 'gamma');
+  assertVqtGamma('vqtToAudio', gamma);
   return requireModule().vqtToAudio(
     magnitude,
     nBins,
@@ -575,6 +580,85 @@ export function analyzeSections(
   return Array.from(sections, (s) => ({ ...s, type: s.type as SectionType }));
 }
 
+/**
+ * Detect structural boundaries and return the novelty curve behind them.
+ *
+ * This is the unlabelled layer {@link analyzeSections} is built on, not a
+ * coarser view of its output: sections are labelled spans, these are the
+ * transitions plus the continuous curve they were picked from, so a caller
+ * applying its own threshold needs this and cannot derive it from a section
+ * list.
+ *
+ * @param request - Samples, sample rate and {@link BoundaryOptions}
+ * @returns The boundaries, the novelty curve, and the analysis grid they live on
+ * @throws {@link SonareError} with `InvalidParameter` when both `useMfcc` and
+ * `useChroma` are `false`: the two feature streams are combined frame-for-frame,
+ * so with neither enabled there is nothing to combine.
+ *
+ * @example
+ * ```ts
+ * const { boundaries, noveltyCurve, noveltyPeak } = detectBoundaries({
+ *   samples,
+ *   sampleRate: 44100,
+ *   absoluteThreshold: 0.01,
+ * });
+ * // `noveltyCurve` is scaled by its own maximum; recover the raw response with
+ * // `noveltyCurve[i] * noveltyPeak`.
+ * ```
+ */
+export function detectBoundaries(request: DetectBoundariesRequest): BoundaryResult {
+  const { samples, sampleRate = 22050 } = request;
+  validateMusicSamples('detectBoundaries', samples, sampleRate, request);
+  // The request IS the options bag: every field is read straight off it, so an
+  // omitted one reaches the embind wrapper absent and takes BoundaryConfig's own
+  // default. Restating the ten defaults here would make them the effective ones
+  // on npm and leave the core's unreachable, and nothing compares the two.
+  const sizes: Record<string, number> = {};
+  for (const name of ['nFft', 'hopLength', 'kernelSize', 'nMfcc', 'nChroma'] as const) {
+    const value = request[name];
+    if (value != null) {
+      sizes[name] = value;
+    }
+  }
+  validatePositiveIntegers('detectBoundaries', sizes);
+  for (const name of ['threshold', 'absoluteThreshold', 'peakDistance'] as const) {
+    const value = request[name];
+    if (value == null) {
+      continue;
+    }
+    assertFiniteScalar('detectBoundaries', value, name);
+    if (value < 0) {
+      throw new RangeError(`detectBoundaries: ${name} must be non-negative`);
+    }
+  }
+  // Only an explicit pair of falses; either one omitted leaves the other stream
+  // on, so there is still something to combine.
+  if (request.useMfcc === false && request.useChroma === false) {
+    throw new SonareError(
+      ErrorCode.InvalidParameter,
+      'InvalidParameter',
+      'detectBoundaries: require useMfcc or useChroma',
+    );
+  }
+  const result = requireModule().detectBoundaries(samples, sampleRate, request);
+  // Re-root the embind array as a plain Array, for the reason analyzeSections
+  // spells out: chaining onto it propagates a constructor structuredClone
+  // rejects, so a result posted from a Worker would fail to clone.
+  return {
+    boundaries: Array.from(result.boundaries, (b) => ({
+      time: b.time,
+      frame: b.frame,
+      strength: b.strength,
+    })),
+    noveltyCurve: result.noveltyCurve,
+    noveltyPeak: result.noveltyPeak,
+    sampleRate: result.sampleRate,
+    hopLength: result.hopLength,
+    nFrames: result.nFrames,
+    frameStride: result.frameStride,
+  };
+}
+
 /** Options for {@link analyzeMelody}. All fields are optional. */
 export interface MelodyOptions {
   /** Lowest f0 (Hz) the tracker will consider. Default 65 (≈ C2). */
@@ -703,8 +787,9 @@ export function onsetEnvelope(
     );
   }
   validateMusicSamples('onsetEnvelope', samples, sampleRate, options);
-  validatePositiveIntegers('onsetEnvelope', { nFft, hopLength, nMels });
-  return requireModule().onsetEnvelope(samples, sampleRate, nFft, hopLength, nMels);
+  const fft = resolveFftOptions('onsetEnvelope', nFft, hopLength);
+  validatePositiveIntegers('onsetEnvelope', { nMels });
+  return requireModule().onsetEnvelope(samples, sampleRate, fft.nFft, fft.hopLength, nMels);
 }
 
 /**
@@ -750,8 +835,16 @@ export function onsetStrengthMulti(
     );
   }
   validateMusicSamples('onsetStrengthMulti', samples, sampleRate, options);
-  validatePositiveIntegers('onsetStrengthMulti', { nFft, hopLength, nMels, nBands });
-  return requireModule().onsetStrengthMulti(samples, sampleRate, nFft, hopLength, nMels, nBands);
+  const fft = resolveFftOptions('onsetStrengthMulti', nFft, hopLength);
+  validatePositiveIntegers('onsetStrengthMulti', { nMels, nBands });
+  return requireModule().onsetStrengthMulti(
+    samples,
+    sampleRate,
+    fft.nFft,
+    fft.hopLength,
+    nMels,
+    nBands,
+  );
 }
 
 /**

package/src/feature_pitch.ts

@@ -1,3 +1,4 @@
+import type { SpectralFrameRequest } from './feature_spectral';
 import { getSonareModule } from './module_state';
 import type { NoteSegment, PiptrackResult, PitchResult } from './public_types';
 
@@ -188,23 +189,117 @@ export function pitchPyin(
 /** Parameters for segmenting an F0 track into stable monophonic notes. */
 export interface NoteSegmentsRequest {
   f0Hz: Float32Array;
+  /**
+   * Per-frame voicing values in `[0, 1]`; anything below `voicedThreshold` is
+   * unvoiced.
+   *
+   * Pass {@link PitchResult.voicedFlag} converted to `0`/`1`. Do **not** pass
+   * {@link pitchPyin}'s `voicedProb`: that value is the frame's voiced
+   * observation mass and rises with F0 for a fixed `frameLength`, so a fixed
+   * threshold silently returns no segments at all for low-register material
+   * (a steady tone below roughly C5 never reaches 0.5).
+   */
   voicedProb: Float32Array;
   frameRate: number;
+  /** Cents of pitch change that start a new segment. Default 50. */
   segmentationThresholdCents?: number;
+  /** Shortest segment kept, in ms. Default 30. */
   minNoteMs?: number;
+  /** Reference pitch each segment's cents are measured against. Default 440. */
   referenceHz?: number;
+  /** Voicing threshold applied to `voicedProb`; defaults to `0.5`. */
+  voicedThreshold?: 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.
+ * and values below `voicedThreshold` (default `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,
+    voicedThreshold: request.voicedThreshold,
   });
 }
+
+// ============================================================================
+// Features - Tuning
+// ============================================================================
+
+export interface PitchTuningRequest {
+  frequencies: Float32Array;
+  resolution?: number;
+  binsPerOctave?: number;
+}
+
+export interface EstimateTuningRequest extends SpectralFrameRequest {
+  resolution?: number;
+  binsPerOctave?: number;
+}
+
+/**
+ * Estimate the global tuning offset from a set of frequencies
+ * (librosa.pitch_tuning). Returns a deviation in fractions of a bin.
+ */
+export function pitchTuning(request: PitchTuningRequest): number;
+export function pitchTuning(
+  frequencies: Float32Array,
+  resolution?: number,
+  binsPerOctave?: number,
+): number;
+export function pitchTuning(
+  frequencies: Float32Array | PitchTuningRequest,
+  resolution = 0.01,
+  binsPerOctave = 12,
+): number {
+  if (!(frequencies instanceof Float32Array)) {
+    const r = frequencies;
+    return pitchTuning(r.frequencies, r.resolution, r.binsPerOctave);
+  }
+  return requireModule().pitchTuning(frequencies, resolution, binsPerOctave);
+}
+
+/**
+ * Estimate the tuning offset of an audio signal (librosa.estimate_tuning).
+ */
+export function estimateTuning(request: EstimateTuningRequest): number;
+export function estimateTuning(
+  samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  resolution?: number,
+  binsPerOctave?: number,
+): number;
+export function estimateTuning(
+  samples: Float32Array | EstimateTuningRequest,
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  resolution = 0.01,
+  binsPerOctave = 12,
+): number {
+  if (!(samples instanceof Float32Array)) {
+    const r = samples;
+    return estimateTuning(
+      r.samples,
+      r.sampleRate,
+      r.nFft,
+      r.hopLength,
+      r.resolution,
+      r.binsPerOctave,
+    );
+  }
+  return requireModule().estimateTuning(
+    samples,
+    sampleRate,
+    nFft,
+    hopLength,
+    resolution,
+    binsPerOctave,
+  );
+}