@libraz/libsonare 1.7.2 → 1.8.0

package/src/quick_analysis.ts

@@ -20,11 +20,13 @@ import type {
   Key,
   KeyCandidate,
   KeyDetectionOptions,
+  MeterEstimate,
   RirResult,
   RirSynthOptions,
   RoomEstimateOptions,
   RoomEstimateResult,
   RoomMorphOptions,
+  RoomMorphResult,
 } from './public_types';
 import { Mode, PitchClass } from './public_types';
 import type { ProgressCallback, WasmAcousticResult } from './sonare.js';
@@ -71,6 +73,8 @@ export interface DetectKeyRequest extends KeyDetectionOptions, SamplesRequest {}
 export interface AnalyzeWithProgressRequest extends SamplesRequest {
   onProgress?: ProgressCallback;
   cancel?: () => boolean;
+  /** Analysis options, with the same fields and defaults {@link analyze} takes. */
+  options?: MusicAnalyzeOptions;
 }
 
 /** Canonical request form for chord detection. */
@@ -147,6 +151,9 @@ export function detectBpm(
 /**
  * Detect musical key from audio samples.
  *
+ * The chroma is read at concert A440; a tuning offset is applied through
+ * {@link analyze}'s `tuning` option (and to chords through {@link detectChords}).
+ *
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz (default: 22050)
  * @returns Detected key
@@ -330,6 +337,7 @@ export function detectChords(
     request.keyMode ?? Mode.Major,
     request.detectInversions ?? false,
     chordChromaMethodValue(request.chromaMethod ?? 'stft'),
+    request.tuning ?? 0,
   );
   return convertChordAnalysisResult(result);
 }
@@ -383,23 +391,13 @@ export function chordFunctionalAnalysis(
     request.useKeyContext ?? false,
     request.detectInversions ?? false,
     chordChromaMethodValue(request.chromaMethod ?? 'stft'),
+    request.tuning ?? 0,
   );
 }
 
 /**
- * Perform complete music analysis.
- *
- * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz (default: 22050)
- * @returns Complete analysis result
- *
- * @remarks
- * This call is synchronous and blocks until analysis completes. Unlike the
- * Node binding (which offers `analyzeAsync` on a libuv worker thread), the
- * WASM build runs on a single thread, so there is no non-blocking variant —
- * the DSP pipeline always runs to completion on the calling thread. To keep
- * the UI responsive for long inputs, drive this from a Web Worker and use
- * {@link analyzeWithProgress} to report progress.
+ * Options for {@link analyze}. Every field is optional and falls back to the
+ * core default when omitted.
  */
 export interface MusicAnalyzeOptions {
   nFft?: number;
@@ -416,9 +414,68 @@ export interface MusicAnalyzeOptions {
   useChordKeyContext?: boolean;
   chordHmmBeamWidth?: number;
   detectChordInversions?: boolean;
+  /**
+   * Track a locally updated tempo prior during beat tracking (default: false).
+   */
+  adaptiveTempo?: boolean;
+  /**
+   * Length of the local tempo context in beats (default: 8). Must be positive.
+   */
+  tempoUpdateIntervalBeats?: number;
+  /**
+   * Decode a per-beat local tempo curve into
+   * {@link AnalysisResult.beatLocalBpm} (default: false).
+   *
+   * @remarks
+   * Off by default because it is an extra output rather than a better analysis:
+   * nothing else in the result changes, and a caller that does not read the
+   * curve would pay a decode over the beat grid for nothing.
+   *
+   * The curve describes the beat grid it was decoded from, and beat tracking
+   * holds a fixed tempo prior unless {@link MusicAnalyzeOptions.adaptiveTempo}
+   * is also set, so measuring a tempo that moves needs both.
+   */
+  computeTempoCurve?: boolean;
+  /**
+   * Meter numerators the estimator scores (default: `[3, 4, 6]`).
+   *
+   * @remarks
+   * Adding a numerator widens the search; it does not force the result. The
+   * list must hold between 1 and 16 entries, each in `[2, 32]`.
+   */
+  meterCandidateNumerators?: number[];
+  /**
+   * Beat unit reported for the detected meter (default: 4). Must be a power of
+   * two in `[1, 32]`. The estimator still reports 8 on its own when it resolves
+   * a compound meter, so this is the unit for everything else.
+   */
+  meterDenominator?: number;
+  /**
+   * Tuning offset of the recording in fractions of a semitone, the unit
+   * `estimateTuning` returns; must be in `[-0.5, 0.5)`. Every chroma the
+   * analysis builds (key, chords, sections) is shifted by it, so a recording
+   * that is not at A440 reads its key and chords on its own pitch grid.
+   * Default 0 (concert A440).
+   */
+  tuning?: number;
 }
 export interface MusicAnalyzeRequest extends SamplesRequest, MusicAnalyzeOptions {}
 
+/**
+ * Perform complete music analysis.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @returns Complete analysis result
+ *
+ * @remarks
+ * This call is synchronous and blocks until analysis completes. Unlike the
+ * Node binding (which offers `analyzeAsync` on a libuv worker thread), the
+ * WASM build runs on a single thread, so there is no non-blocking variant —
+ * the DSP pipeline always runs to completion on the calling thread. To keep
+ * the UI responsive for long inputs, drive this from a Web Worker and use
+ * {@link analyzeWithProgress} to report progress.
+ */
 export function analyze(request: MusicAnalyzeRequest): AnalysisResult;
 export function analyze(
   samples: Float32Array,
@@ -436,6 +493,98 @@ export function analyze(
   return convertAnalysisResult(result);
 }
 
+/**
+ * Canonical request form for {@link estimateMeter}.
+ *
+ * @remarks
+ * Every scoring field is optional and falls back to the core default when
+ * omitted; the core validates them and rejects a value it cannot answer rather
+ * than substituting one.
+ */
+export interface EstimateMeterRequest {
+  /** Beat positions in seconds, non-decreasing. */
+  beatTimes: ArrayLike<number>;
+  /**
+   * Per-beat accent value, the same length as {@link beatTimes}.
+   *
+   * @remarks
+   * `AnalysisResult.beatObservations.onsetStrength` is the intended source —
+   * it is the windowed value the library's own downbeat pass scores.
+   * `beats[].strength` also works but is a single unwindowed envelope frame.
+   * Neither needs pre-scaling: the series is divided by its own maximum before
+   * scoring, so only the accent contrast within it is read.
+   *
+   * A series assembled by hand from {@link onsetEnvelope} — one frame read at
+   * each beat time — is neither of those, and it carries a sample-rate
+   * dependence neither of them has: a hop counted in samples frames a different
+   * amount of time at each rate, so one waveform sampled at 32000, 44100 and
+   * 48000 Hz has produced three different winning numerators off beat times
+   * identical to the sample. Widening the read to a window around the beat does
+   * not remove it. A browser decodes at the output device's rate, so that is a
+   * different answer per visitor for the same clip.
+   */
+  beatStrengths: ArrayLike<number>;
+  /**
+   * Meter numerators to score (default: `[3, 4, 6]`).
+   *
+   * @remarks
+   * Adding a numerator widens the search; it does not force the result. The
+   * list must hold between 1 and 16 entries, each in `[2, 32]`.
+   */
+  candidateNumerators?: number[];
+  /**
+   * Beat unit reported for the detected meter (default: 4). Must be a power of
+   * two in `[1, 32]`.
+   *
+   * @remarks
+   * Reported as requested: whether a beat divides into three is measured from
+   * energy *between* the beats, which per-beat accents do not carry, so a
+   * compound meter is not resolvable here. A six accented 3+3 comes back with
+   * this denominator and `grouping === [3, 3]`.
+   */
+  denominator?: number;
+  /** Weight of the downbeat accent term (default: 1). */
+  downbeatWeight?: number;
+  /** Weight of the measure-periodicity term (default: 0.5). */
+  measureWeight?: number;
+  /** Weight of the subdivision term (default: 0.15). */
+  subdivisionWeight?: number;
+  /**
+   * Score ratio above which a compound meter is preferred (default: 0.85).
+   *
+   * @remarks
+   * Only consulted when there is a subdivision to measure, so it has no effect
+   * here — this entry point scores per-beat accents alone.
+   */
+  compoundSubdivisionThreshold?: number;
+}
+
+/**
+ * Estimate meter over a caller-supplied beat series.
+ *
+ * @param request - Beat series plus optional scoring configuration
+ * @returns The selected signature, its downbeat phase and grouping, and the
+ *   scored candidates
+ *
+ * @remarks
+ * Scores only the per-beat strengths, so no audio and no frame-level onset
+ * envelope is needed: an arbitrary span of an existing analysis can be scored
+ * without re-running it. Pass `beatObservations.onsetStrength` rather than
+ * `beats[].strength` — see {@link EstimateMeterRequest.beatStrengths}.
+ *
+ * The result carries `grouping` alongside the numerator: how the bar divides
+ * into accent groups of two and three beats, so a seven comes back as `[3, 2,
+ * 2]` or `[2, 2, 3]` rather than as a bare seven.
+ *
+ * Check `searched` before reading anything as a detection: a series too short
+ * to score any candidate reports a fixed fallback instead, and `candidateScores`
+ * grows with the square root of how many beats were scored, so scores from
+ * spans of different lengths are not directly comparable.
+ */
+export function estimateMeter(request: EstimateMeterRequest): MeterEstimate {
+  return requireModule().estimateMeter(request.beatTimes, request.beatStrengths, request);
+}
+
 export function analyzeImpulseResponse(request: AnalyzeImpulseResponseRequest): AcousticResult;
 export function analyzeImpulseResponse(
   samples: Float32Array,
@@ -451,9 +600,11 @@ export function analyzeImpulseResponse(
 ): AcousticResult {
   const request =
     samples instanceof Float32Array ? { samples, sampleRate, nOctaveBands, minDecayDb } : samples;
-  if (request.minDecayDb === null) {
-    throw new TypeError('analyzeImpulseResponse: minDecayDb must be a finite number');
-  }
+  // Only `undefined` takes the default. `null` falls through to
+  // assertFiniteScalar, which refuses it with the same wording as any other
+  // non-finite value -- Number.isFinite(null) is false, so the case needs no
+  // branch of its own, and the one that was here answered it with a different
+  // error class than the check three lines down.
   const resolvedMinDecayDb = request.minDecayDb === undefined ? 30.0 : request.minDecayDb;
   assertFiniteScalar('analyzeImpulseResponse', resolvedMinDecayDb, 'minDecayDb');
   if (resolvedMinDecayDb <= 0) {
@@ -536,20 +687,23 @@ export function estimateRoom(
 
 /**
  * Morph a recording's reverberation toward a target room (creative FX, not
- * dereverberation). Returns the morphed samples (input length plus the target
- * room's reverb tail).
+ * dereverberation).
+ *
+ * Returns the morphed samples in `audio` (input length plus the target room's
+ * reverb tail) alongside the target-room synthesis's own `diagnostics`, which
+ * report a room other than the one requested — see {@link RoomMorphResult}.
  */
-export function roomMorph(request: RoomMorphRequest): Float32Array;
+export function roomMorph(request: RoomMorphRequest): RoomMorphResult;
 export function roomMorph(
   samples: Float32Array,
   sampleRate: number,
   options?: RoomMorphOptions,
-): Float32Array;
+): RoomMorphResult;
 export function roomMorph(
   samples: Float32Array | RoomMorphRequest,
   sampleRate?: number,
   options: RoomMorphOptions = {},
-): Float32Array {
+): RoomMorphResult {
   const module = requireModule();
   if (typeof module.roomMorph !== 'function') {
     throw new Error('libsonare was built without acoustic-simulation support');
@@ -575,15 +729,17 @@ export function analyzeWithProgress(
   samples: Float32Array,
   sampleRate: number | undefined,
   onProgress: ProgressCallback,
+  options?: MusicAnalyzeOptions,
 ): AnalysisResult;
 export function analyzeWithProgress(
   samples: Float32Array | AnalyzeWithProgressRequest,
   sampleRate = 22050,
   onProgress?: ProgressCallback,
+  options?: MusicAnalyzeOptions,
 ): AnalysisResult {
   const request: AnalyzeWithProgressRequest =
     samples instanceof Float32Array
-      ? { samples, sampleRate, onProgress: onProgress as ProgressCallback }
+      ? { samples, sampleRate, onProgress: onProgress as ProgressCallback, options }
       : samples;
   validateAnalysisInput(
     'analyzeWithProgress',
@@ -591,9 +747,11 @@ export function analyzeWithProgress(
     request.sampleRate ?? 22050,
     request,
   );
+  // The module reads options with the same reader analyze uses.
   const result = requireModule().analyzeWithProgress(
     request.samples,
     request.sampleRate ?? 22050,
+    request.options ?? {},
     request.onProgress ?? (() => {}),
     request.cancel ?? (() => false),
   );
@@ -619,11 +777,24 @@ export interface RhythmAnalysisResult {
   grooveType: string;
   patternRegularity: number;
   tempoStability: number;
+  /**
+   * The beat tracker's own tempo, refined from the local beat period. It is a
+   * third figure rather than either tempo entry point's: measured against
+   * synthesized click trains it differs from both at every sample rate, and
+   * lands closer to the known tempo than either. Analysed at the sample rate
+   * you pass, so `nFft` and `hopLength` are in samples of your buffer.
+   */
   bpm: number;
   beatIntervals: Float32Array;
 }
 
-export interface DynamicsAnalysisResult {
+/**
+ * Dynamics metrics returned by {@link analyzeDynamics}.
+ *
+ * The Node package declares the same shape under the same name; the two are
+ * pinned to one field list by `tests/conformance/shared_type_shapes.json`.
+ */
+export interface DynamicsResult {
   dynamicRangeDb: number;
   peakDb: number;
   rmsDb: number;
@@ -636,6 +807,12 @@ export interface DynamicsAnalysisResult {
   loudnessRmsDb: Float32Array;
 }
 
+/**
+ * @deprecated Use {@link DynamicsResult}. Retained so code written against the
+ * WASM-only spelling keeps compiling; the Node package exports the same alias.
+ */
+export type DynamicsAnalysisResult = DynamicsResult;
+
 /** Timbre metrics for one analysis window. Entries are ordered by time in `timbreOverTime`. */
 export interface TimbreFrame {
   brightness: number;
@@ -713,17 +890,17 @@ export function analyzeRhythm(
 /**
  * Dynamics analysis (RMS, peak, crest factor, LRA, loudness curve).
  */
-export function analyzeDynamics(request: AnalyzeDynamicsRequest): DynamicsAnalysisResult;
+export function analyzeDynamics(request: AnalyzeDynamicsRequest): DynamicsResult;
 export function analyzeDynamics(
   samples: Float32Array,
   sampleRate?: number,
   options?: AnalyzeDynamicsOptions,
-): DynamicsAnalysisResult;
+): DynamicsResult;
 export function analyzeDynamics(
   samples: Float32Array | AnalyzeDynamicsRequest,
   sampleRate = 22050,
   options: AnalyzeDynamicsOptions = {},
-): DynamicsAnalysisResult {
+): DynamicsResult {
   const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
   validateAnalysisInput('analyzeDynamics', request.samples, request.sampleRate ?? 22050, request);
   return requireModule().analyzeDynamics(