@libraz/libsonare 1.5.3 → 1.5.5

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "type": "module",
   "packageManager": "yarn@4.15.0",
-  "description": "Audio analysis library for music information retrieval",
+  "description": "Audio analysis, mastering, mixing, and MIDI synthesis in WebAssembly",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -47,6 +47,17 @@
     "bpm",
     "key",
     "tempo",
+    "chords",
+    "audio-processing",
+    "dsp",
+    "mastering",
+    "mixing",
+    "loudness",
+    "lufs",
+    "midi",
+    "synthesizer",
+    "soundfont",
+    "room-acoustics",
     "wasm",
     "webassembly"
   ],
@@ -59,7 +70,7 @@
   "bugs": {
     "url": "https://github.com/libraz/libsonare/issues"
   },
-  "homepage": "https://github.com/libraz/libsonare#readme",
+  "homepage": "https://libsonare.libraz.net",
   "engines": {
     "node": ">=18.0.0"
   },

package/src/_chain_config.ts

@@ -22,25 +22,5 @@ export function flattenChainConfig(config: MasteringChainConfig): Record<string,
   };
   walk(config as ChainSection, '');
 
-  // Compatibility aliases for the original WASM-only shorthand. Normalize at
-  // this boundary so every native entry point receives the core parser's one
-  // canonical vocabulary; public types can migrate to the nested spelling
-  // without preserving a second C++ parser indefinitely.
-  const aliases: Record<string, string> = {
-    'repair.denoise': 'repair.denoise.enabled',
-    'repair.nFft': 'repair.denoise.nFft',
-    'repair.hopLength': 'repair.denoise.hopLength',
-    'repair.ddAlpha': 'repair.denoise.ddAlpha',
-    'repair.gainFloor': 'repair.denoise.gainFloor',
-    'eq.tiltDb': 'eq.tilt.tiltDb',
-    'eq.pivotHz': 'eq.tilt.pivotHz',
-  };
-  for (const [legacy, canonical] of Object.entries(aliases)) {
-    const value = out[legacy];
-    if (value !== undefined) {
-      out[canonical] = value;
-      delete out[legacy];
-    }
-  }
   return out;
 }

package/src/analysis_helpers.ts

@@ -16,6 +16,25 @@ import type {
   WasmKeyCandidateResult,
 } from './sonare.js';
 
+const PITCH_CLASS_NAMES = [
+  'C',
+  'C#',
+  'D',
+  'D#',
+  'E',
+  'F',
+  'F#',
+  'G',
+  'G#',
+  'A',
+  'A#',
+  'B',
+] as const;
+
+function pitchClassName(value: number): string {
+  return PITCH_CLASS_NAMES[value] ?? 'C';
+}
+
 export function convertKeyCandidate(wasm: WasmKeyCandidateResult): KeyCandidate {
   return {
     key: {
@@ -89,6 +108,8 @@ export function convertChordAnalysisResult(wasm: WasmChordAnalysisResult): Chord
     chords: wasm.chords.map((c) => ({
       root: c.root as PitchClass,
       bass: c.bass as PitchClass,
+      rootName: pitchClassName(c.root),
+      bassName: pitchClassName(c.bass),
       quality: c.quality as ChordQuality,
       start: c.start,
       end: c.end,
@@ -129,6 +150,8 @@ export function convertAnalysisResult(wasm: WasmAnalysisResult): AnalysisResult
     chords: wasm.chords.map((c) => ({
       root: c.root as PitchClass,
       bass: c.bass as PitchClass,
+      rootName: pitchClassName(c.root),
+      bassName: pitchClassName(c.bass),
       quality: c.quality as ChordQuality,
       start: c.start,
       end: c.end,

package/src/audio.ts

@@ -76,6 +76,7 @@ import {
   detectOnsets,
 } from './quick_analysis';
 import type { ProgressCallback, WasmNnlsChromaResult } from './sonare.js';
+import { validateAudioBuffer } from './validation';
 
 // ============================================================================
 // Audio Class
@@ -177,7 +178,8 @@ export class Audio {
    *   Node/Python surfaces).
    */
   static fromBuffer(samples: Float32Array, sampleRate = 48000): Audio {
-    return new Audio(samples, sampleRate);
+    validateAudioBuffer(samples, sampleRate);
+    return new Audio(samples.slice(), sampleRate);
   }
 
   /**
@@ -472,7 +474,7 @@ export class Audio {
     hopLength = 512,
     fmin = 65.0,
     fmax = 2093.0,
-    threshold = 0.3,
+    threshold = 0.1,
     fillNa = false,
   ): PitchResult {
     return pitchYin(
@@ -492,7 +494,7 @@ export class Audio {
     hopLength = 512,
     fmin = 65.0,
     fmax = 2093.0,
-    threshold = 0.3,
+    threshold = 0.1,
     fillNa = false,
   ): PitchResult {
     return pitchPyin(

package/src/codes.ts

@@ -20,6 +20,8 @@ export function panLawCode(panLaw: PanLaw | number): number {
     return panLaw;
   }
   switch (panLaw) {
+    case 'const3dB':
+      return 0;
     case 'const4.5dB':
       return 1;
     case 'const6dB':
@@ -27,7 +29,7 @@ export function panLawCode(panLaw: PanLaw | number): number {
     case 'linear0dB':
       return 3;
     default:
-      return 0;
+      throw new Error(`Invalid pan law: ${panLaw}`);
   }
 }
 
@@ -36,6 +38,8 @@ export function panModeCode(panMode: PanMode | number): number {
     return panMode;
   }
   switch (panMode) {
+    case 'balance':
+      return 0;
     case 'stereoPan':
     case 'stereo-pan':
       return 1;
@@ -43,19 +47,38 @@ export function panModeCode(panMode: PanMode | number): number {
     case 'dual-pan':
       return 2;
     default:
-      return 0;
+      throw new Error(`Invalid pan mode: ${panMode}`);
   }
 }
 
 export function meterTapCode(tap: MeterTap | number): number {
-  return tap === 'preFader' || tap === 0 ? 0 : 1;
+  if (typeof tap === 'number') {
+    return tap;
+  }
+  switch (tap) {
+    case 'preFader':
+      return 0;
+    case 'postFader':
+      return 1;
+    default:
+      throw new Error(`Invalid meter tap: ${tap}`);
+  }
 }
 
 export function sendTimingCode(timing: SendTiming | number): number {
   // Mirrors SonareSendTiming: post-fader is 0 (so an omitted/zeroed value is
   // post-fader), pre-fader is 1. A raw number is passed through as the C ABI int.
+  // An unknown string is rejected rather than silently routed to post-fader,
+  // matching the sibling enum-code helpers and Node's sendTimingValue.
   if (typeof timing === 'number') {
     return timing;
   }
-  return timing === 'preFader' ? 1 : 0;
+  switch (timing) {
+    case 'postFader':
+      return 0;
+    case 'preFader':
+      return 1;
+    default:
+      throw new Error(`Invalid send timing: ${timing}`);
+  }
 }

package/src/effects_transform.ts

@@ -34,13 +34,13 @@ export interface PercussiveRequest extends ValidateOptions {
 
 export interface TimeStretchRequest extends ValidateOptions {
   samples: Float32Array;
-  sampleRate: number;
+  sampleRate?: number;
   rate: number;
 }
 
 export interface PitchShiftRequest extends ValidateOptions {
   samples: Float32Array;
-  sampleRate: number;
+  sampleRate?: number;
   semitones: number;
 }
 
@@ -79,7 +79,7 @@ export interface NoteMoveRequest extends NoteMoveOptions, ValidateOptions {
 
 export interface NormalizeRequest extends ValidateOptions {
   samples: Float32Array;
-  sampleRate: number;
+  sampleRate?: number;
   targetDb?: number;
 }
 
@@ -177,7 +177,7 @@ export function percussive(
  * Time-stretch audio without changing pitch.
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz
+ * @param sampleRate - Sample rate in Hz (default: 22050)
  * @param rate - Time stretch rate (0.5 = double duration, 2.0 = half duration)
  * @returns Time-stretched audio
  */
@@ -196,17 +196,17 @@ export function timeStretch(
 ): Float32Array {
   const request: TimeStretchRequest =
     samples instanceof Float32Array
-      ? { samples, sampleRate: sampleRate as number, rate: rate as number, ...options }
+      ? { samples, sampleRate, rate: rate as number, ...options }
       : samples;
   assertSamples('timeStretch', request.samples, request.validate !== false);
-  return requireModule().timeStretch(request.samples, request.sampleRate, request.rate);
+  return requireModule().timeStretch(request.samples, request.sampleRate ?? 22050, request.rate);
 }
 
 /**
  * Pitch-shift audio without changing duration.
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz
+ * @param sampleRate - Sample rate in Hz (default: 22050)
  * @param semitones - Pitch shift in semitones (+12 = one octave up, -12 = one octave down)
  * @returns Pitch-shifted audio
  */
@@ -225,15 +225,23 @@ export function pitchShift(
 ): Float32Array {
   const request: PitchShiftRequest =
     samples instanceof Float32Array
-      ? { samples, sampleRate: sampleRate as number, semitones: semitones as number, ...options }
+      ? { samples, sampleRate, semitones: semitones as number, ...options }
       : samples;
   assertSamples('pitchShift', request.samples, request.validate !== false);
-  return requireModule().pitchShift(request.samples, request.sampleRate, request.semitones);
+  return requireModule().pitchShift(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.semitones,
+  );
 }
 
 /**
  * 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. 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
@@ -275,7 +283,8 @@ export function pitchCorrectToMidi(
  * 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` (non-zero = voiced) and `voicedProb` ([0,1]) are optional;
- * omitting them treats every frame as voiced.
+ * omitting them treats every frame as voiced. An `f0Hz` NaN is accepted only
+ * when the corresponding `voiced` entry is zero, matching pYIN output.
  *
  * @param samples - Audio samples (mono, float32)
  * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
@@ -350,7 +359,8 @@ export function pitchCorrectToMidiTimevarying(
  * 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.
+ * 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)
@@ -407,7 +417,7 @@ export function pitchCorrectTimevarying(
  * @param sampleRate - Sample rate in Hz
  * @param onsetSample - Note onset position in samples
  * @param offsetSample - Note offset position in samples
- * @param stretchRatio - Stretch ratio (0.5 = double duration, 2.0 = half duration)
+ * @param stretchRatio - Stretch ratio (0.5 = half duration, 2.0 = double duration)
  * @returns Audio with the note region stretched
  */
 export function noteStretch(request: NoteStretchRequest): Float32Array;
@@ -427,7 +437,7 @@ export function noteStretch(
     request.samples,
     request.sampleRate ?? 22050,
     request.onsetSample ?? 0,
-    request.offsetSample ?? 0,
+    request.offsetSample ?? request.samples.length,
     request.stretchRatio ?? 1.0,
   );
 }
@@ -450,7 +460,7 @@ export function noteMove(
     request.samples,
     request.sampleRate ?? 22050,
     request.onsetSample ?? 0,
-    request.offsetSample ?? 0,
+    request.offsetSample ?? request.samples.length,
     request.targetOnsetSample ?? 0,
   );
 }
@@ -459,8 +469,8 @@ export function noteMove(
  * Normalize audio to target peak level.
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz
- * @param targetDb - Target peak level in dB (default: 0 dB = full scale)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale)
  * @returns Normalized audio
  */
 export function normalize(request: NormalizeRequest): Float32Array;
@@ -477,11 +487,13 @@ export function normalize(
   options: ValidateOptions = {},
 ): Float32Array {
   const request: NormalizeRequest =
-    samples instanceof Float32Array
-      ? { samples, sampleRate: sampleRate as number, targetDb, ...options }
-      : samples;
+    samples instanceof Float32Array ? { samples, sampleRate, targetDb, ...options } : samples;
   assertSamples('normalize', request.samples, request.validate !== false);
-  return requireModule().normalize(request.samples, request.sampleRate, request.targetDb ?? 0.0);
+  return requireModule().normalize(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.targetDb ?? 0.0,
+  );
 }
 
 /**

package/src/feature_core.ts

@@ -81,6 +81,14 @@ export interface PcenRequest {
   values: Float32Array;
   nBins: number;
   nFrames: number;
+  sampleRate?: number;
+  hopLength?: number;
+  timeConstant?: number;
+  gain?: number;
+  bias?: number;
+  power?: number;
+  eps?: number;
+  /** @deprecated Put PCEN fields directly on the request object. */
   options?: Record<string, number>;
 }
 export interface TempogramRequest {
@@ -449,7 +457,17 @@ export function pcen(
 ): Float32Array {
   if (!(values instanceof Float32Array)) {
     const r = values;
-    return pcen(r.values, r.nBins, r.nFrames, r.options);
+    const {
+      values: requestValues,
+      nBins: requestBins,
+      nFrames: requestFrames,
+      options: legacyOptions,
+      ...flatOptions
+    } = r;
+    return pcen(requestValues, requestBins, requestFrames, {
+      ...legacyOptions,
+      ...flatOptions,
+    });
   }
   return requireModule().pcen(values, nBins, nFrames, options);
 }

package/src/feature_music.ts

@@ -1,3 +1,4 @@
+import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type {
   AnalyzeSectionsOptions,
@@ -97,6 +98,9 @@ export interface LufsRequest extends ValidateOptions {
 export interface NnlsChromaRequest extends GuardedOptions {
   samples: Float32Array;
   sampleRate?: number;
+  enableStftBlend?: boolean;
+  stftBlendWeight?: number;
+  stftBlendNFft?: number;
 }
 
 function validateMusicSamples(
@@ -139,18 +143,24 @@ export function nnlsChroma(request: NnlsChromaRequest): WasmNnlsChromaResult;
 export function nnlsChroma(
   samples: Float32Array,
   sampleRate?: number,
-  options?: GuardedOptions,
+  options?: Omit<NnlsChromaRequest, 'samples' | 'sampleRate'>,
 ): WasmNnlsChromaResult;
 export function nnlsChroma(
   samples: Float32Array | NnlsChromaRequest,
   sampleRate = 22050,
-  options: GuardedOptions = {},
+  options: Omit<NnlsChromaRequest, 'samples' | 'sampleRate'> = {},
 ): WasmNnlsChromaResult {
   if (!(samples instanceof Float32Array)) {
     return nnlsChroma(samples.samples, samples.sampleRate, samples);
   }
   validateMusicSamples('nnlsChroma', samples, sampleRate, options);
-  return requireModule().nnlsChroma(samples, sampleRate);
+  return requireModule().nnlsChroma(
+    samples,
+    sampleRate,
+    options.enableStftBlend ?? true,
+    options.stftBlendWeight ?? 0.55,
+    options.stftBlendNFft ?? 4096,
+  );
 }
 
 /**
@@ -306,7 +316,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; 0 is equivalent to CQT (default: 0)
+ * @param gamma - Bandwidth offset; negative 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;
@@ -327,7 +338,7 @@ export function vqt(
   fmin = 32.70319566257483,
   nBins = 84,
   binsPerOctave = 12,
-  gamma = 0,
+  gamma = -1,
   options: GuardedOptions = {},
 ): CqtResult {
   if (!(samples instanceof Float32Array)) {
@@ -347,9 +358,6 @@ export function vqt(
   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);
 }
 
@@ -464,7 +472,7 @@ export function vqtToAudio(
   hopLength = 512,
   fmin = 32.70319566257483,
   binsPerOctave = 12,
-  gamma = 0,
+  gamma = -1,
   nIter = 32,
   options: GuardedOptions = {},
 ): Float32Array {
@@ -496,9 +504,6 @@ export function vqtToAudio(
     options,
   );
   assertFiniteScalar('vqtToAudio', gamma, 'gamma');
-  if (gamma < 0) {
-    throw new RangeError('vqtToAudio: gamma must be non-negative');
-  }
   return requireModule().vqtToAudio(
     magnitude,
     nBins,
@@ -543,8 +548,8 @@ export function analyzeSections(
     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');
+  if ((options.minSectionSec ?? 4.0) < 0) {
+    throw new RangeError('analyzeSections: minSectionSec must be non-negative');
   }
   // The embind value marshalling returns an array whose constructor is not this
   // realm's Array; chaining .map() onto it propagates that constructor via
@@ -614,10 +619,15 @@ export function analyzeMelody(
   const fmax = options.fmax ?? 2093.0;
   validateFrequencyBounds('analyzeMelody', fmin, fmax);
   // The melody tracker's fmin is a YIN pitch floor: 0 is meaningless, and the
-  // flat C ABI (sonare_analyze_melody) rejects it. validateFrequencyBounds only
-  // guards fmin >= 0, so enforce strict positivity here for parity.
+  // flat C ABI (sonare_analyze_melody) rejects it with InvalidParameter.
+  // validateFrequencyBounds only guards fmin >= 0, so enforce strict positivity
+  // here and report the same branded error the Node/Python surfaces raise.
   if (fmin <= 0) {
-    throw new RangeError('analyzeMelody: fmin must be positive');
+    throw new SonareError(
+      ErrorCode.InvalidParameter,
+      'InvalidParameter',
+      'analyzeMelody: fmin must be positive',
+    );
   }
   validatePositiveIntegers('analyzeMelody', {
     frameLength: options.frameLength ?? 2048,
@@ -626,7 +636,11 @@ export function analyzeMelody(
   const threshold = options.threshold ?? 0.1;
   assertFiniteScalar('analyzeMelody', threshold, 'threshold');
   if (threshold <= 0) {
-    throw new RangeError('analyzeMelody: threshold must be positive');
+    throw new SonareError(
+      ErrorCode.InvalidParameter,
+      'InvalidParameter',
+      'analyzeMelody: threshold must be positive',
+    );
   }
   return requireModule().analyzeMelody(
     samples,

package/src/feature_pitch.ts

@@ -18,8 +18,8 @@ function requireModule() {
  * @param hopLength - Hop length (default: 512)
  * @param fmin - Minimum frequency in Hz (default: 65)
  * @param fmax - Maximum frequency in Hz (default: 2093)
- * @param threshold - YIN threshold (default: 0.3)
- * @param fillNa - If true, return 0 for unvoiced f0 frames; otherwise keep NaN (default: false)
+ * @param threshold - YIN threshold (default: 0.1)
+ * @param fillNa - Retained for compatibility; YIN always returns a finite per-frame estimate.
  * @returns Pitch detection result
  */
 export interface PitchYinRequest {
@@ -51,7 +51,7 @@ export function pitchYin(
   hopLength = 512,
   fmin = 65.0,
   fmax = 2093.0,
-  threshold = 0.3,
+  threshold = 0.1,
   fillNa = false,
 ): PitchResult {
   if (!(samples instanceof Float32Array)) {
@@ -88,7 +88,7 @@ export function pitchYin(
  * @param hopLength - Hop length (default: 512)
  * @param fmin - Minimum frequency in Hz (default: 65)
  * @param fmax - Maximum frequency in Hz (default: 2093)
- * @param threshold - YIN threshold (default: 0.3)
+ * @param threshold - YIN threshold (default: 0.1)
  * @param fillNa - If true, return 0 for unvoiced f0 frames; otherwise keep NaN (default: false)
  * @returns Pitch detection result
  */
@@ -112,7 +112,7 @@ export function pitchPyin(
   hopLength = 512,
   fmin = 65.0,
   fmax = 2093.0,
-  threshold = 0.3,
+  threshold = 0.1,
   fillNa = false,
 ): PitchResult {
   if (!(samples instanceof Float32Array)) {

package/src/feature_spectral.ts

@@ -438,21 +438,21 @@ export function remix(
 export function phaseVocoder(request: PhaseVocoderRequest): Float32Array;
 export function phaseVocoder(
   samples: Float32Array,
+  sampleRate: number,
   rate: number,
-  sampleRate?: number,
   nFft?: number,
   hopLength?: number,
 ): Float32Array;
 export function phaseVocoder(
   samples: Float32Array | PhaseVocoderRequest,
-  rate = 1,
   sampleRate = 22050,
+  rate = 1,
   nFft = 2048,
   hopLength = 512,
 ): Float32Array {
   if (!(samples instanceof Float32Array)) {
     const r = samples;
-    return phaseVocoder(r.samples, r.rate, r.sampleRate, r.nFft, r.hopLength);
+    return phaseVocoder(r.samples, r.sampleRate ?? 22050, r.rate, r.nFft, r.hopLength);
   }
   return requireModule().phaseVocoder(samples, sampleRate, rate, nFft, hopLength);
 }