@libraz/libsonare 1.7.1 → 1.8.0

package/src/effects_timepitch.ts

@@ -0,0 +1,377 @@
+/**
+ * Time and pitch transforms over a whole buffer: stretching, shifting, and
+ * correction onto a target pitch.
+ */
+
+import { toVoicedFloat32 } from './_effects_common';
+import { resolveFftOptions } from './_fft_options';
+import { getSonareModule } from './module_state';
+import type { PitchCorrectOptions, VoicedFlags } from './public_types';
+import type { ValidateOptions } from './validation';
+import { assertFiniteScalar, assertSamples } from './validation';
+
+function requireModule() {
+  return getSonareModule();
+}
+
+export interface TimeStretchRequest extends ValidateOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+  rate: number;
+  nFft?: number;
+  hopLength?: number;
+}
+
+export interface PitchShiftRequest extends ValidateOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+  semitones: number;
+  nFft?: number;
+  hopLength?: number;
+}
+
+export interface PitchCorrectToMidiRequest extends ValidateOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+  currentMidi?: number;
+  targetMidi?: number;
+}
+
+export interface PitchCorrectToMidiTimevaryingRequest extends ValidateOptions {
+  samples: Float32Array;
+  f0Hz: Float32Array;
+  targetMidi: number;
+  sampleRate?: number;
+  hopLength?: number;
+  voiced?: VoicedFlags;
+  voicedProb?: Float32Array;
+}
+
+export interface PitchCorrectTimevaryingRequest extends PitchCorrectOptions {
+  samples: Float32Array;
+  f0Hz: Float32Array;
+  sampleRate?: number;
+  hopLength?: number;
+}
+
+/**
+ * Time-stretch audio without changing pitch.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param rate - Time stretch rate (0.5 = double duration, 2.0 = half duration)
+ * @param nFft - FFT size: an even integer >= 2 (default 2048)
+ * @param hopLength - Hop in samples, in `(0, nFft / 2]` (default 512), so
+ *   frames overlap by at least half a window
+ * @returns Time-stretched audio
+ */
+export function timeStretch(request: TimeStretchRequest): Float32Array;
+export function timeStretch(
+  samples: Float32Array,
+  sampleRate: number,
+  rate: number,
+  options?: ValidateOptions,
+): Float32Array;
+export function timeStretch(
+  samples: Float32Array,
+  sampleRate: number,
+  rate: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: ValidateOptions,
+): Float32Array;
+export function timeStretch(
+  samples: Float32Array | TimeStretchRequest,
+  sampleRate?: number,
+  rate?: number,
+  nFftOrOptions?: number | ValidateOptions,
+  hopLength?: number,
+  options: ValidateOptions = {},
+): Float32Array {
+  if (
+    nFftOrOptions !== undefined &&
+    nFftOrOptions !== null &&
+    typeof nFftOrOptions !== 'number' &&
+    typeof nFftOrOptions !== 'object'
+  ) {
+    throw new TypeError('timeStretch: nFft must be an integer or options object');
+  }
+  if (nFftOrOptions === null) {
+    throw new TypeError('timeStretch: nFft must be an integer or options object');
+  }
+  const positionalOptions =
+    typeof nFftOrOptions === 'object' && nFftOrOptions !== null ? nFftOrOptions : options;
+  const positionalNFft = typeof nFftOrOptions === 'number' ? nFftOrOptions : undefined;
+  const request: TimeStretchRequest =
+    samples instanceof Float32Array
+      ? {
+          samples,
+          sampleRate,
+          rate: rate as number,
+          nFft: positionalNFft,
+          hopLength,
+          ...positionalOptions,
+        }
+      : samples;
+  assertSamples('timeStretch', request.samples, request.validate !== false);
+  // Matches the addon, which refuses a non-finite rate here rather than letting
+  // the core answer it. Does NOT cover a finite value too wide for a float:
+  // Number.isFinite(1e39) is true and the demotion to the f32 parameter makes it
+  // an infinity, which only the binding-side narrowing can see.
+  assertFiniteScalar('timeStretch', request.rate as number, 'rate');
+  const fftOptions = resolveFftOptions('timeStretch', request.nFft, request.hopLength);
+  return requireModule().timeStretchEx(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.rate,
+    fftOptions.nFft,
+    fftOptions.hopLength,
+  );
+}
+
+/**
+ * Pitch-shift audio without changing duration.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param semitones - Pitch shift in semitones (+12 = one octave up, -12 = one octave down)
+ * @param nFft - FFT size: an even integer >= 2 (default 2048)
+ * @param hopLength - Hop in samples, in `(0, nFft / 2]` (default 512), so
+ *   frames overlap by at least half a window
+ * @returns Pitch-shifted audio
+ */
+export function pitchShift(request: PitchShiftRequest): Float32Array;
+export function pitchShift(
+  samples: Float32Array,
+  sampleRate: number,
+  semitones: number,
+  options?: ValidateOptions,
+): Float32Array;
+export function pitchShift(
+  samples: Float32Array,
+  sampleRate: number,
+  semitones: number,
+  nFft?: number,
+  hopLength?: number,
+  options?: ValidateOptions,
+): Float32Array;
+export function pitchShift(
+  samples: Float32Array | PitchShiftRequest,
+  sampleRate?: number,
+  semitones?: number,
+  nFftOrOptions?: number | ValidateOptions,
+  hopLength?: number,
+  options: ValidateOptions = {},
+): Float32Array {
+  if (
+    nFftOrOptions !== undefined &&
+    nFftOrOptions !== null &&
+    typeof nFftOrOptions !== 'number' &&
+    typeof nFftOrOptions !== 'object'
+  ) {
+    throw new TypeError('pitchShift: nFft must be an integer or options object');
+  }
+  if (nFftOrOptions === null) {
+    throw new TypeError('pitchShift: nFft must be an integer or options object');
+  }
+  const positionalOptions =
+    typeof nFftOrOptions === 'object' && nFftOrOptions !== null ? nFftOrOptions : options;
+  const positionalNFft = typeof nFftOrOptions === 'number' ? nFftOrOptions : undefined;
+  const request: PitchShiftRequest =
+    samples instanceof Float32Array
+      ? {
+          samples,
+          sampleRate,
+          semitones: semitones as number,
+          nFft: positionalNFft,
+          hopLength,
+          ...positionalOptions,
+        }
+      : samples;
+  assertSamples('pitchShift', request.samples, request.validate !== false);
+  // See timeStretch above for what this does and does not cover.
+  assertFiniteScalar('pitchShift', request.semitones as number, 'semitones');
+  const fftOptions = resolveFftOptions('pitchShift', request.nFft, request.hopLength);
+  return requireModule().pitchShiftEx(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.semitones,
+    fftOptions.nFft,
+    fftOptions.hopLength,
+  );
+}
+
+/**
+ * Pitch-correct audio from a current MIDI note to a target MIDI note.
+ *
+ * Applies one constant, immediate transpose with no retune glide and preserves
+ * the input buffer length. The whole interval is applied however large it is:
+ * both endpoints are validated to [0, 127], so a two-octave move such as
+ * C3 -> C5 transposes by the full 24 semitones. Use
+ * {@link pitchCorrectToMidiTimevarying} for a caller-supplied pitch contour.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param currentMidi - Detected/current MIDI note number
+ * @param targetMidi - Desired MIDI note number
+ * @returns Pitch-corrected audio
+ */
+export function pitchCorrectToMidi(request: PitchCorrectToMidiRequest): Float32Array;
+export function pitchCorrectToMidi(
+  samples: Float32Array,
+  sampleRate?: number,
+  currentMidi?: number,
+  targetMidi?: number,
+  options?: ValidateOptions,
+): Float32Array;
+export function pitchCorrectToMidi(
+  samples: Float32Array | PitchCorrectToMidiRequest,
+  sampleRate = 22050,
+  currentMidi = 69.0,
+  targetMidi = 69.0,
+  options: ValidateOptions = {},
+): Float32Array {
+  const request =
+    samples instanceof Float32Array
+      ? { samples, sampleRate, currentMidi, targetMidi, ...options }
+      : samples;
+  assertSamples('pitchCorrectToMidi', request.samples, request.validate !== false);
+  return requireModule().pitchCorrectToMidi(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.currentMidi ?? 69.0,
+    request.targetMidi ?? 69.0,
+  );
+}
+
+/**
+ * Contour-following ("time-varying") pitch correction toward a MIDI target.
+ *
+ * Unlike {@link pitchCorrectToMidi} (a single constant transpose), this follows
+ * the caller-supplied per-frame `f0Hz` contour and retunes every voiced frame
+ * toward `targetMidi`, so vibrato/drift in the source is tracked rather than
+ * flattened. `voiced` (truthy = voiced) and `voicedProb` ([0,1]) are optional;
+ * omitting them treats every frame as voiced. An `f0Hz` NaN is accepted only
+ * when the corresponding `voiced` entry is falsy, matching pYIN output. The
+ * `voicedFlag` / `voicedProb` arrays of a {@link PitchResult} can be passed
+ * through directly.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
+ * @param targetMidi - Desired MIDI note number
+ * @param sampleRate - Sample rate in Hz
+ * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
+ * @param voiced - Optional per-frame voiced flags (truthy = voiced)
+ * @param voicedProb - Optional per-frame voicing probability in [0, 1]
+ * @returns Pitch-corrected audio
+ */
+export function pitchCorrectToMidiTimevarying(
+  request: PitchCorrectToMidiTimevaryingRequest,
+): Float32Array;
+export function pitchCorrectToMidiTimevarying(
+  samples: Float32Array,
+  f0Hz: Float32Array,
+  targetMidi: number,
+  sampleRate?: number,
+  hopLength?: number,
+  voiced?: VoicedFlags,
+  voicedProb?: Float32Array,
+  options?: ValidateOptions,
+): Float32Array;
+export function pitchCorrectToMidiTimevarying(
+  samples: Float32Array | PitchCorrectToMidiTimevaryingRequest,
+  f0Hz?: Float32Array,
+  targetMidi?: number,
+  sampleRate = 22050,
+  hopLength = 512,
+  voiced?: VoicedFlags,
+  voicedProb?: Float32Array,
+  options: ValidateOptions = {},
+): Float32Array {
+  const request: PitchCorrectToMidiTimevaryingRequest =
+    samples instanceof Float32Array
+      ? {
+          samples,
+          f0Hz: f0Hz as Float32Array,
+          targetMidi: targetMidi as number,
+          sampleRate,
+          hopLength,
+          voiced,
+          voicedProb,
+          ...options,
+        }
+      : samples;
+  assertSamples('pitchCorrectToMidiTimevarying', request.samples, request.validate !== false);
+  if (request.voiced && request.voiced.length !== request.f0Hz.length) {
+    throw new RangeError('pitchCorrectToMidiTimevarying: voiced length must match f0Hz length');
+  }
+  if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
+    throw new RangeError('pitchCorrectToMidiTimevarying: voicedProb length must match f0Hz length');
+  }
+  const voicedF32 = request.voiced ? toVoicedFloat32(request.voiced) : undefined;
+  return requireModule().pitchCorrectToMidiTimevarying(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.f0Hz,
+    request.targetMidi,
+    request.hopLength ?? 512,
+    voicedF32,
+    request.voicedProb,
+  );
+}
+
+/**
+ * Contour-following pitch correction toward a fixed MIDI note OR a musical
+ * scale, with tunable retune strength and vibrato preservation.
+ *
+ * Generalises {@link pitchCorrectToMidiTimevarying}: the same caller-supplied
+ * per-frame `f0Hz` contour drives correction, but `options.mode` selects between
+ * a fixed-MIDI target (`'midi'`, default) and scale quantisation (`'scale'`),
+ * and the retune knobs shape natural-vs-robotic correction. An `f0Hz` NaN is
+ * accepted only for a frame marked unvoiced.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
+ * @param sampleRate - Sample rate in Hz
+ * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
+ * @param options - Target mode + retune knobs + optional voiced/voicedProb arrays
+ * @returns Pitch-corrected audio
+ */
+export function pitchCorrectTimevarying(request: PitchCorrectTimevaryingRequest): Float32Array;
+export function pitchCorrectTimevarying(
+  samples: Float32Array,
+  f0Hz: Float32Array,
+  sampleRate?: number,
+  hopLength?: number,
+  options?: PitchCorrectOptions,
+): Float32Array;
+export function pitchCorrectTimevarying(
+  samples: Float32Array | PitchCorrectTimevaryingRequest,
+  f0Hz?: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  options: PitchCorrectOptions = {},
+): Float32Array {
+  const request: PitchCorrectTimevaryingRequest =
+    samples instanceof Float32Array
+      ? { samples, f0Hz: f0Hz as Float32Array, sampleRate, hopLength, ...options }
+      : samples;
+  assertSamples('pitchCorrectTimevarying', request.samples, request.validate !== false);
+  if (request.voiced && request.voiced.length !== request.f0Hz.length) {
+    throw new RangeError('pitchCorrectTimevarying: voiced length must match f0Hz length');
+  }
+  if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
+    throw new RangeError('pitchCorrectTimevarying: voicedProb length must match f0Hz length');
+  }
+  const nativeOptions = {
+    ...request,
+    voiced: request.voiced ? toVoicedFloat32(request.voiced) : undefined,
+  };
+  return requireModule().pitchCorrectTimevarying(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.f0Hz,
+    request.hopLength ?? 512,
+    nativeOptions,
+  );
+}

package/src/errors.ts

@@ -13,6 +13,7 @@ export enum ErrorCode {
   NotSupported = 6,
   InvalidState = 7,
   Cancelled = 8,
+  EncodeFailed = 9,
   Unknown = 99,
 }
 
@@ -20,6 +21,10 @@ export enum ErrorCode {
  * Error thrown by libsonare on a native (C++) failure. Carries a numeric
  * {@link ErrorCode} `code` plus its canonical `codeName`, so callers can branch
  * on the cause instead of matching message text.
+ *
+ * Narrow a caught value with {@link isSonareError} or with `instanceof`; both
+ * accept the same values. The Node package exports the same class under the
+ * same name.
  */
 export class SonareError extends Error {
   /** Numeric error code, equal to an {@link ErrorCode} value. */
@@ -33,9 +38,26 @@ export class SonareError extends Error {
     this.code = code;
     this.codeName = codeName;
   }
+
+  /**
+   * Brand-based `instanceof`: an error that carries the shape narrows here even
+   * when it is not literally an instance of this class. That is not a
+   * hypothetical — an error posted from the analysis worker arrives as a
+   * structured clone with its prototype gone, which a prototype-based
+   * `instanceof` would silently miss. Delegates to {@link isSonareError} so the
+   * two never disagree.
+   */
+  static [Symbol.hasInstance](value: unknown): value is SonareError {
+    return isSonareError(value);
+  }
 }
 
-/** Type guard: whether a caught value is a libsonare {@link SonareError}. */
+/**
+ * Type guard: whether a caught value is a libsonare {@link SonareError}.
+ *
+ * Duck-typed on purpose: a value that crossed a worker boundary has lost its
+ * prototype, so a prototype check would miss it.
+ */
 export function isSonareError(value: unknown): value is SonareError {
   return (
     value instanceof Error &&

package/src/feature_core.ts

@@ -104,6 +104,72 @@ export interface SilenceRequest {
   hopLength?: number;
 }
 
+/** Canonical request form for the common-silence union of several signals. */
+export interface SplitSilenceCommonRequest {
+  signals: Float32Array[];
+  topDb?: number;
+  frameLength?: number;
+  hopLength?: number;
+}
+
+/**
+ * Why {@link splitSilenceCommonWithReport} found the gaps it did.
+ *
+ * One interval covering everything is the answer to three different situations
+ * and the interval list cannot separate them: no take has a quiet moment at all,
+ * the takes each have one but not in the same place, or `topDb` was set too loose
+ * to see the ones they have.
+ *
+ * **Read {@link silenceCeilingDb} against the `topDb` that was passed**, which is
+ * the whole decision:
+ *
+ * - ceiling near 0 — a take is sounding continuously. No threshold helps, and a
+ *   cut point has to come from somewhere other than silence.
+ * - ceiling below `topDb` — the threshold was too loose to see the quiet these
+ *   takes do have. A `topDb` under the reported ceiling finds it.
+ * - ceiling at or above `topDb`, and still one interval — every take shows silence
+ *   at this setting and they do not share any of it. That is the alignment case,
+ *   and it is what {@link alignTakeToReference} is for.
+ *
+ * The figures come from the same RMS pass the intervals do, so they can never
+ * describe a different measurement.
+ */
+export interface SilenceCommonReport {
+  /**
+   * The largest `topDb` at which EVERY signal still shows silence.
+   *
+   * A frame counts as silent when it sits at least `topDb` under its own signal's
+   * peak RMS, so each signal's deepest dip decides whether any threshold can find
+   * silence in it, and the union needs all of them quiet at once — hence the
+   * minimum across the signals. 0 for an all-silent signal, where the peak is 0
+   * and the ratio has no value; 120 is the floor the dB conversion clamps at,
+   * reported for a signal holding a zero-valued frame.
+   */
+  silenceCeilingDb: number;
+  /**
+   * How many intervals the most fragmented signal produced alone, counted before
+   * the union merges anything.
+   *
+   * A measure of shape rather than of cause: 1 is a take that sounds once and
+   * stops, so a take that is loud then silent counts 1 exactly as a take with no
+   * silence does. Use {@link silenceCeilingDb} to tell those apart; use these two
+   * to see whether any take has an interior gap at all (`>= 2`) and whether the
+   * takes differ in how broken up they are (`maxSignalIntervals !==
+   * minSignalIntervals`).
+   */
+  maxSignalIntervals: number;
+  /** How many intervals the least fragmented signal produced alone. */
+  minSignalIntervals: number;
+}
+
+/** Result of {@link splitSilenceCommonWithReport}. */
+export interface SplitSilenceCommonWithReportResult {
+  /** Exactly what {@link splitSilenceCommon} returns for the same arguments. */
+  intervals: Int32Array;
+  /** Why those are the intervals. */
+  report: SilenceCommonReport;
+}
+
 export interface FrameSignalRequest {
   samples: Float32Array;
   frameLength: number;
@@ -228,6 +294,12 @@ export interface PlpRequest {
 /**
  * Convert frequency in Hz to Mel scale.
  *
+ * A total function, matching the C ABI and librosa: a non-finite `hz`
+ * propagates rather than throwing, and a magnitude past the 32-bit float range
+ * saturates to an infinity the same way the C conversion does. Out-of-audio
+ * frequencies are not refused either — the mapping is defined over the whole
+ * real line.
+ *
  * @param hz - Frequency in Hz
  * @returns Mel frequency
  */
@@ -236,7 +308,8 @@ export function hzToMel(hz: number): number {
 }
 
 /**
- * Convert Mel scale to frequency in Hz.
+ * Convert Mel scale to frequency in Hz. Total over the same domain as
+ * {@link hzToMel}.
  *
  * @param mel - Mel frequency
  * @returns Frequency in Hz
@@ -248,6 +321,11 @@ export function melToHz(mel: number): number {
 /**
  * Convert frequency in Hz to MIDI note number.
  *
+ * Total, like {@link hzToMel}. A non-positive `hz` returns `-Infinity`, the log2
+ * limit, and {@link midiToHz} maps that back to 0. A NaN propagates, which is
+ * what makes a default `pitchPyin` track — whose unvoiced frames are NaN — safe
+ * to map through.
+ *
  * @param hz - Frequency in Hz
  * @returns MIDI note number (A4 = 440 Hz = 69)
  */
@@ -256,7 +334,8 @@ export function hzToMidi(hz: number): number {
 }
 
 /**
- * Convert MIDI note number to frequency in Hz.
+ * Convert MIDI note number to frequency in Hz. Total, like {@link hzToMel};
+ * `-Infinity` bottoms out at 0 rather than propagating its sign.
  *
  * @param midi - MIDI note number
  * @returns Frequency in Hz
@@ -268,6 +347,11 @@ export function midiToHz(midi: number): number {
 /**
  * Convert frequency in Hz to note name.
  *
+ * Every frequency with no note answers `"?"` rather than throwing: zero,
+ * negative, past the representable MIDI range, and non-finite alike. A default
+ * `pitchPyin` track fills unvoiced frames with NaN, so mapping one through this
+ * yields `"?"` at those frames.
+ *
  * @param hz - Frequency in Hz
  * @returns Note name (e.g., "A4", "C#5")
  */
@@ -427,6 +511,47 @@ export function splitSilence(
   return requireModule().splitSilence(samples, topDb, frameLength, hopLength);
 }
 
+/**
+ * Lists the intervals where ANY of `signals` is sounding, so every gap
+ * between them is silent in all of them -- what several takes of one part
+ * share is their silence, not their sound.
+ *
+ * @returns The union of {@link splitSilence}'s per-signal intervals, merged
+ *   where they touch. A single signal returns exactly what `splitSilence`
+ *   does for it.
+ */
+export function splitSilenceCommon(request: SplitSilenceCommonRequest): Int32Array {
+  return requireModule().splitSilenceCommon(
+    request.signals,
+    request.topDb ?? 60.0,
+    request.frameLength ?? 2048,
+    request.hopLength ?? 512,
+  );
+}
+
+/**
+ * {@link splitSilenceCommon} plus the report that says why those are the
+ * intervals.
+ *
+ * Identical intervals, identical refusals, identical defaults; the only
+ * difference is the second field. The plain entry point stays because a caller
+ * cutting takes has no use for the diagnosis, and one interval covering
+ * everything is the answer to three different situations the interval list cannot
+ * separate — see {@link SilenceCommonReport} for reading them apart.
+ *
+ * @returns The union intervals and the report measured on the same RMS pass
+ */
+export function splitSilenceCommonWithReport(
+  request: SplitSilenceCommonRequest,
+): SplitSilenceCommonWithReportResult {
+  return requireModule().splitSilenceCommonWithReport(
+    request.signals,
+    request.topDb ?? 60.0,
+    request.frameLength ?? 2048,
+    request.hopLength ?? 512,
+  );
+}
+
 export function frameSignal(request: FrameSignalRequest): WasmFrameResult;
 export function frameSignal(
   samples: Float32Array,