@libraz/libsonare 1.5.3 → 1.5.4

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "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/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,10 +225,14 @@ 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,
+  );
 }
 
 /**
@@ -459,7 +463,7 @@ export function noteMove(
  * Normalize audio to target peak level.
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz
+ * @param sampleRate - Sample rate in Hz (default: 22050)
  * @param targetDb - Target peak level in dB (default: 0 dB = full scale)
  * @returns Normalized audio
  */
@@ -477,11 +481,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_music.ts

@@ -1,3 +1,4 @@
+import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type {
   AnalyzeSectionsOptions,
@@ -614,10 +615,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 +632,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/metering.ts

@@ -383,8 +383,10 @@ export function meteringStereoCorrelation(
 }
 
 /**
- * Side / mid energy ratio, clamped to `[0, 2]`: 0 = pure mono, ~1 = wide
- * stereo, 2 = fully decorrelated / out-of-phase.
+ * Side / mid energy ratio in `[0, +Infinity)`: 0 = pure mono, ~1 = wide stereo,
+ * larger = increasingly decorrelated / out-of-phase. The value is unbounded and
+ * returns `Infinity` when the mid channel is silent (a mono-collapsed / fully
+ * out-of-phase signal).
  */
 export function meteringStereoWidth(request: MeteringStereoRequest): number;
 export function meteringStereoWidth(

package/src/project_class.ts

@@ -427,6 +427,19 @@ export class Project {
     this.native.redo();
   }
 
+  /** Clear the undo/redo history without changing the current project state. */
+  clearHistory(): void {
+    this.native.clearHistory();
+  }
+
+  /** Cap the undo history depth (clamped to >= 1); evicts oldest entries beyond the cap. */
+  setMaxUndoDepth(depth: number): void {
+    if (!Number.isInteger(depth) || depth < 1) {
+      throw new RangeError('Project.setMaxUndoDepth: depth must be an integer >= 1');
+    }
+    this.native.setMaxUndoDepth(depth);
+  }
+
   /** Replace a MIDI clip's entire event list. */
   setMidiEvents(
     clipId: number,

package/src/project_internal.ts

@@ -58,6 +58,8 @@ export interface WasmProject {
   setTrackPan: (trackId: number, pan: number) => void;
   undo: () => void;
   redo: () => void;
+  clearHistory: () => void;
+  setMaxUndoDepth: (depth: number) => void;
   setMidiEvents: (
     clipId: number,
     events: ReadonlyArray<ProjectMidiEvent | readonly [number, number, number]>,

package/src/realtime_voice_changer.ts

@@ -1,5 +1,77 @@
 import { getSonareModule } from './module_state';
-import type { RealtimeVoiceChangerConfigInput, VoicePresetId } from './public_types';
+import type {
+  RealtimeVoiceChangerConfigInput,
+  RealtimeVoiceChangerPodConfig,
+  VoicePresetId,
+} from './public_types';
+
+/**
+ * True when `config` is a flat POD (the shape `realtimeVoiceChangerPresetConfig`
+ * returns) rather than a preset name or a nested preset. `retuneSemitones` only
+ * exists on the flat POD; the nested form spells it `retune.semitones`.
+ */
+function isFlatVoiceChangerPod(config: unknown): config is RealtimeVoiceChangerPodConfig {
+  return typeof config === 'object' && config !== null && 'retuneSemitones' in config;
+}
+
+/**
+ * Rewrite the flat 36-field POD into the nested shape the native config parser
+ * reads. Passing the flat POD straight to `setConfig` would leave every nested
+ * field at its default (only the three root fields are read flat), silently
+ * discarding retune/EQ/reverb/etc.
+ */
+function flatVoiceChangerPodToNested(pod: RealtimeVoiceChangerPodConfig): Record<string, unknown> {
+  return {
+    inputGainDb: pod.inputGainDb,
+    outputGainDb: pod.outputGainDb,
+    wetMix: pod.wetMix,
+    retune: { semitones: pod.retuneSemitones, mix: pod.retuneMix, grainSize: pod.retuneGrainSize },
+    formant: {
+      factor: pod.formantFactor,
+      amount: pod.formantAmount,
+      body: pod.formantBody,
+      brightness: pod.formantBrightness,
+      nasal: pod.formantNasal,
+    },
+    eq: {
+      highpassHz: pod.eqHighpassHz,
+      bodyDb: pod.eqBodyDb,
+      presenceDb: pod.eqPresenceDb,
+      airDb: pod.eqAirDb,
+    },
+    gate: {
+      thresholdDb: pod.gateThresholdDb,
+      attackMs: pod.gateAttackMs,
+      releaseMs: pod.gateReleaseMs,
+      rangeDb: pod.gateRangeDb,
+    },
+    compressor: {
+      thresholdDb: pod.compressorThresholdDb,
+      ratio: pod.compressorRatio,
+      attackMs: pod.compressorAttackMs,
+      releaseMs: pod.compressorReleaseMs,
+      makeupGainDb: pod.compressorMakeupGainDb,
+    },
+    deesser: {
+      frequencyHz: pod.deesserFrequencyHz,
+      thresholdDb: pod.deesserThresholdDb,
+      ratio: pod.deesserRatio,
+      rangeDb: pod.deesserRangeDb,
+    },
+    reverb: {
+      mix: pod.reverbMix,
+      timeMs: pod.reverbTimeMs,
+      damping: pod.reverbDamping,
+      seed: pod.reverbSeed,
+    },
+    limiter: {
+      ceilingDb: pod.limiterCeilingDb,
+      releaseMs: pod.limiterReleaseMs,
+      enableIspLimiter: pod.limiterEnableIspLimiter,
+      ispCeilingDbtp: pod.limiterIspCeilingDbtp,
+    },
+  };
+}
 
 /**
  * Zero-copy realtime buffer pair for {@link RealtimeVoiceChanger} mono
@@ -58,8 +130,12 @@ export class RealtimeVoiceChanger {
     this.changer.reset();
   }
 
-  setConfig(config: RealtimeVoiceChangerConfigInput): void {
-    this.changer.setConfig(config as Record<string, unknown> | string);
+  setConfig(config: RealtimeVoiceChangerConfigInput | RealtimeVoiceChangerPodConfig): void {
+    // A flat POD (from realtimeVoiceChangerPresetConfig) is rewritten to the
+    // nested shape the native parser reads; a preset name or nested preset is
+    // passed through unchanged.
+    const resolved = isFlatVoiceChangerPod(config) ? flatVoiceChangerPodToNested(config) : config;
+    this.changer.setConfig(resolved as Record<string, unknown> | string);
   }
 
   configJson(): string {

package/src/sonare.js.d.ts

@@ -745,6 +745,10 @@ export interface WasmEngineTransportState {
   barCount: number;
   /** Time signature in effect at the current PPQ. */
   timeSignature: { numerator: number; denominator: number; confidence: number };
+  /** One-based beat within the current bar (`barCount` is zero-based). */
+  beat: number;
+  /** Fractional position within the current beat, in [0, 1). */
+  beatFraction: number;
 }
 
 export interface WasmEngineBounceOptions {