@libraz/libsonare 1.5.3 → 1.5.5

package/dist/index.js

@@ -200,6 +200,10 @@ function assertSampleRate(fnName, sampleRate) {
     );
   }
 }
+function validateAudioBuffer(samples, sampleRate) {
+  assertSamples("Audio.fromBuffer", samples, true);
+  assertSampleRate("Audio.fromBuffer", sampleRate);
+}
 function assertNonNegativeInteger(fnName, value, argName) {
   if (!Number.isInteger(value) || value < 0) {
     throw new RangeError(`${fnName}: ${argName} must be a non-negative integer`);
@@ -244,12 +248,16 @@ function percussive(samples, sampleRate = 22050, options = {}) {
 function timeStretch(samples, sampleRate, rate, options = {}) {
   const request = samples instanceof Float32Array ? { samples, sampleRate, rate, ...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);
 }
 function pitchShift(samples, sampleRate, semitones, options = {}) {
   const request = samples instanceof Float32Array ? { samples, sampleRate, semitones, ...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
+  );
 }
 function pitchCorrectToMidi(samples, sampleRate = 22050, currentMidi = 69, targetMidi = 69, options = {}) {
   const request = samples instanceof Float32Array ? { samples, sampleRate, currentMidi, targetMidi, ...options } : samples;
@@ -318,7 +326,7 @@ function noteStretch(samples, sampleRate = 22050, options = {}) {
     request.samples,
     request.sampleRate ?? 22050,
     request.onsetSample ?? 0,
-    request.offsetSample ?? 0,
+    request.offsetSample ?? request.samples.length,
     request.stretchRatio ?? 1
   );
 }
@@ -329,14 +337,18 @@ function noteMove(samples, sampleRate = 22050, options = {}) {
     request.samples,
     request.sampleRate ?? 22050,
     request.onsetSample ?? 0,
-    request.offsetSample ?? 0,
+    request.offsetSample ?? request.samples.length,
     request.targetOnsetSample ?? 0
   );
 }
 function normalize(samples, sampleRate, targetDb = 0, options = {}) {
   const request = 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);
+  return requireModule().normalize(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.targetDb ?? 0
+  );
 }
 function spectralEdit(samples, sampleRate, ops = [], options = {}) {
   const request = samples instanceof Float32Array ? { samples, sampleRate, ops, ...options } : samples;
@@ -397,22 +409,6 @@ function flattenChainConfig(config) {
     }
   };
   walk(config, "");
-  const aliases = {
-    "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 !== void 0) {
-      out[canonical] = value;
-      delete out[legacy];
-    }
-  }
   return out;
 }
 
@@ -972,7 +968,17 @@ function vectorNormalize(values, normType = 0, threshold = 0) {
 function pcen(values, nBins = 0, nFrames = 0, options = {}) {
   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 requireModule8().pcen(values, nBins, nFrames, options);
 }
@@ -1048,7 +1054,13 @@ function nnlsChroma(samples, sampleRate = 22050, options = {}) {
     return nnlsChroma(samples.samples, samples.sampleRate, samples);
   }
   validateMusicSamples("nnlsChroma", samples, sampleRate, options);
-  return requireModule9().nnlsChroma(samples, sampleRate);
+  return requireModule9().nnlsChroma(
+    samples,
+    sampleRate,
+    options.enableStftBlend ?? true,
+    options.stftBlendWeight ?? 0.55,
+    options.stftBlendNFft ?? 4096
+  );
 }
 function cqt(samples, sampleRate = 22050, hopLength = 512, fmin = 32.70319566257483, nBins = 84, binsPerOctave = 12, options = {}) {
   if (!(samples instanceof Float32Array)) {
@@ -1104,7 +1116,7 @@ function hybridCqt(samples, sampleRate = 22050, hopLength = 512, fmin = 32.70319
   validateFrequencyBounds("hybridCqt", fmin);
   return requireModule9().hybridCqt(samples, sampleRate, hopLength, fmin, nBins, binsPerOctave);
 }
-function vqt(samples, sampleRate = 22050, hopLength = 512, fmin = 32.70319566257483, nBins = 84, binsPerOctave = 12, gamma = 0, options = {}) {
+function vqt(samples, sampleRate = 22050, hopLength = 512, fmin = 32.70319566257483, nBins = 84, binsPerOctave = 12, gamma = -1, options = {}) {
   if (!(samples instanceof Float32Array)) {
     const request = samples;
     return vqt(
@@ -1122,9 +1134,6 @@ function vqt(samples, sampleRate = 22050, hopLength = 512, fmin = 32.70319566257
   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 requireModule9().vqt(samples, sampleRate, hopLength, fmin, nBins, binsPerOctave, gamma);
 }
 function validateCqtInverse(fnName, magnitude, nBins, nFrames, sampleRate, hopLength, fmin, binsPerOctave, nIter, options) {
@@ -1180,7 +1189,7 @@ function cqtToAudio(magnitude, nBins = 0, nFrames = 0, sampleRate = 22050, hopLe
     nIter
   );
 }
-function vqtToAudio(magnitude, nBins = 0, nFrames = 0, sampleRate = 22050, hopLength = 512, fmin = 32.70319566257483, binsPerOctave = 12, gamma = 0, nIter = 32, options = {}) {
+function vqtToAudio(magnitude, nBins = 0, nFrames = 0, sampleRate = 22050, hopLength = 512, fmin = 32.70319566257483, binsPerOctave = 12, gamma = -1, nIter = 32, options = {}) {
   if (!(magnitude instanceof Float32Array)) {
     const request = magnitude;
     return vqtToAudio(
@@ -1209,9 +1218,6 @@ function vqtToAudio(magnitude, nBins = 0, nFrames = 0, sampleRate = 22050, hopLe
     options
   );
   assertFiniteScalar("vqtToAudio", gamma, "gamma");
-  if (gamma < 0) {
-    throw new RangeError("vqtToAudio: gamma must be non-negative");
-  }
   return requireModule9().vqtToAudio(
     magnitude,
     nBins,
@@ -1235,8 +1241,8 @@ function analyzeSections(samples, sampleRate = 22050, options = {}) {
     hopLength: options.hopLength ?? 512
   });
   assertFiniteScalar("analyzeSections", options.minSectionSec ?? 4, "minSectionSec");
-  if ((options.minSectionSec ?? 4) <= 0) {
-    throw new RangeError("analyzeSections: minSectionSec must be positive");
+  if ((options.minSectionSec ?? 4) < 0) {
+    throw new RangeError("analyzeSections: minSectionSec must be non-negative");
   }
   const sections = requireModule9().analyzeSections(
     samples,
@@ -1257,7 +1263,11 @@ function analyzeMelody(samples, sampleRate = 22050, options = {}) {
   const fmax = options.fmax ?? 2093;
   validateFrequencyBounds("analyzeMelody", fmin, fmax);
   if (fmin <= 0) {
-    throw new RangeError("analyzeMelody: fmin must be positive");
+    throw new SonareError(
+      4 /* InvalidParameter */,
+      "InvalidParameter",
+      "analyzeMelody: fmin must be positive"
+    );
   }
   validatePositiveIntegers("analyzeMelody", {
     frameLength: options.frameLength ?? 2048,
@@ -1266,7 +1276,11 @@ function analyzeMelody(samples, sampleRate = 22050, options = {}) {
   const threshold = options.threshold ?? 0.1;
   assertFiniteScalar("analyzeMelody", threshold, "threshold");
   if (threshold <= 0) {
-    throw new RangeError("analyzeMelody: threshold must be positive");
+    throw new SonareError(
+      4 /* InvalidParameter */,
+      "InvalidParameter",
+      "analyzeMelody: threshold must be positive"
+    );
   }
   return requireModule9().analyzeMelody(
     samples,
@@ -1378,7 +1392,7 @@ function shortTermLufs(samples, sampleRate = 22050, options = {}) {
 function requireModule10() {
   return getSonareModule();
 }
-function pitchYin(samples, sampleRate = 22050, frameLength = 2048, hopLength = 512, fmin = 65, fmax = 2093, threshold = 0.3, fillNa = false) {
+function pitchYin(samples, sampleRate = 22050, frameLength = 2048, hopLength = 512, fmin = 65, fmax = 2093, threshold = 0.1, fillNa = false) {
   if (!(samples instanceof Float32Array)) {
     const request = samples;
     return pitchYin(
@@ -1403,7 +1417,7 @@ function pitchYin(samples, sampleRate = 22050, frameLength = 2048, hopLength = 5
     fillNa
   );
 }
-function pitchPyin(samples, sampleRate = 22050, frameLength = 2048, hopLength = 512, fmin = 65, fmax = 2093, threshold = 0.3, fillNa = false) {
+function pitchPyin(samples, sampleRate = 22050, frameLength = 2048, hopLength = 512, fmin = 65, fmax = 2093, threshold = 0.1, fillNa = false) {
   if (!(samples instanceof Float32Array)) {
     const request = samples;
     return pitchPyin(
@@ -1559,10 +1573,10 @@ function remix(samples, intervals, sampleRate = 22050, alignZeros = false) {
   const intervalsI32 = intervals instanceof Int32Array ? intervals : Int32Array.from(intervals, (v) => Math.trunc(v));
   return requireModule12().remix(samples, intervalsI32, sampleRate, alignZeros);
 }
-function phaseVocoder(samples, rate = 1, sampleRate = 22050, nFft = 2048, hopLength = 512) {
+function phaseVocoder(samples, sampleRate = 22050, rate = 1, nFft = 2048, hopLength = 512) {
   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 requireModule12().phaseVocoder(samples, sampleRate, rate, nFft, hopLength);
 }
@@ -1692,7 +1706,7 @@ function stftDb(samples, sampleRate = 22050, nFft = 2048, hopLength = 512, optio
   validatePositiveIntegers2("stftDb", { nFft, hopLength });
   return requireModule13().stftDb(samples, sampleRate, nFft, hopLength);
 }
-function chromaCens(samples, sampleRate = 22050, hopLength = 512, nChroma = 12, options = {}) {
+function chromaCens(samples, sampleRate = 22050, hopLength = 512, nChroma = 12, binsPerOctave = 36, options = {}) {
   if (!(samples instanceof Float32Array)) {
     const request = samples;
     return chromaCens(
@@ -1700,14 +1714,18 @@ function chromaCens(samples, sampleRate = 22050, hopLength = 512, nChroma = 12,
       request.sampleRate,
       request.hopLength,
       request.nChroma,
+      request.binsPerOctave,
       request
     );
   }
   validateSpectrogramSamples("chromaCens", samples, sampleRate, options);
-  validatePositiveIntegers2("chromaCens", { hopLength, nChroma });
-  return requireModule13().chromaCens(samples, sampleRate, hopLength, nChroma);
+  validatePositiveIntegers2("chromaCens", { hopLength, nChroma, binsPerOctave });
+  if (binsPerOctave % nChroma !== 0) {
+    throw new RangeError("chromaCens: binsPerOctave must be a multiple of nChroma");
+  }
+  return requireModule13().chromaCens(samples, sampleRate, hopLength, nChroma, binsPerOctave);
 }
-function chromaCqt(samples, sampleRate = 22050, hopLength = 512, nChroma = 12, options = {}) {
+function chromaCqt(samples, sampleRate = 22050, hopLength = 512, nChroma = 12, binsPerOctave = 36, options = {}) {
   if (!(samples instanceof Float32Array)) {
     const request = samples;
     return chromaCqt(
@@ -1715,12 +1733,16 @@ function chromaCqt(samples, sampleRate = 22050, hopLength = 512, nChroma = 12, o
       request.sampleRate,
       request.hopLength,
       request.nChroma,
+      request.binsPerOctave,
       request
     );
   }
   validateSpectrogramSamples("chromaCqt", samples, sampleRate, options);
-  validatePositiveIntegers2("chromaCqt", { hopLength, nChroma });
-  return requireModule13().chromaCqt(samples, sampleRate, hopLength, nChroma);
+  validatePositiveIntegers2("chromaCqt", { hopLength, nChroma, binsPerOctave });
+  if (binsPerOctave % nChroma !== 0) {
+    throw new RangeError("chromaCqt: binsPerOctave must be a multiple of nChroma");
+  }
+  return requireModule13().chromaCqt(samples, sampleRate, hopLength, nChroma, binsPerOctave);
 }
 function bassChroma(samples, sampleRate = 22050, hopLength = 512, nChroma = 12, options = {}) {
   if (!(samples instanceof Float32Array)) {
@@ -1854,7 +1876,7 @@ function melToAudio(melPower, nMels = 0, nFrames = 0, sampleRate = 22050, nFft =
     htk
   );
 }
-function mfccToMel(mfccCoefficients, nMfcc = 0, nFrames = 0, nMels = 128, options = {}) {
+function mfccToMel(mfccCoefficients, nMfcc = 0, nFrames = 0, nMels = 128, lifter = 0, options = {}) {
   if (!(mfccCoefficients instanceof Float32Array)) {
     const request = mfccCoefficients;
     return mfccToMel(
@@ -1862,6 +1884,7 @@ function mfccToMel(mfccCoefficients, nMfcc = 0, nFrames = 0, nMels = 128, option
       request.nMfcc,
       request.nFrames,
       request.nMels,
+      request.lifter,
       request
     );
   }
@@ -1875,9 +1898,9 @@ function mfccToMel(mfccCoefficients, nMfcc = 0, nFrames = 0, nMels = 128, option
     options
   );
   validatePositiveIntegers2("mfccToMel", { nMels });
-  return requireModule13().mfccToMel(mfccCoefficients, nMfcc, nFrames, nMels);
+  return requireModule13().mfccToMel(mfccCoefficients, nMfcc, nFrames, nMels, lifter);
 }
-function mfccToAudio(mfccCoefficients, nMfcc = 0, nFrames = 0, nMels = 128, sampleRate = 22050, nFft = 2048, hopLength = 512, fmin = 0, fmax = 0, nIter = 32, htk = false, options = {}) {
+function mfccToAudio(mfccCoefficients, nMfcc = 0, nFrames = 0, nMels = 128, sampleRate = 22050, nFft = 2048, hopLength = 512, fmin = 0, fmax = 0, nIter = 32, htk = false, lifter = 0, options = {}) {
   if (!(mfccCoefficients instanceof Float32Array)) {
     const request = mfccCoefficients;
     return mfccToAudio(
@@ -1892,6 +1915,7 @@ function mfccToAudio(mfccCoefficients, nMfcc = 0, nFrames = 0, nMels = 128, samp
       request.fmax,
       request.nIter,
       request.htk,
+      request.lifter,
       request
     );
   }
@@ -1918,7 +1942,8 @@ function mfccToAudio(mfccCoefficients, nMfcc = 0, nFrames = 0, nMels = 128, samp
     fmin,
     fmax,
     nIter,
-    htk
+    htk,
+    lifter
   );
 }
 function chroma(samples, sampleRate = 22050, nFft = 2048, hopLength = 512, options = {}) {
@@ -1995,6 +2020,23 @@ var SectionType = {
 };
 
 // src/analysis_helpers.ts
+var PITCH_CLASS_NAMES = [
+  "C",
+  "C#",
+  "D",
+  "D#",
+  "E",
+  "F",
+  "F#",
+  "G",
+  "G#",
+  "A",
+  "A#",
+  "B"
+];
+function pitchClassName(value) {
+  return PITCH_CLASS_NAMES[value] ?? "C";
+}
 function convertKeyCandidate(wasm) {
   return {
     key: {
@@ -2065,6 +2107,8 @@ function convertChordAnalysisResult(wasm) {
     chords: wasm.chords.map((c) => ({
       root: c.root,
       bass: c.bass,
+      rootName: pitchClassName(c.root),
+      bassName: pitchClassName(c.bass),
       quality: c.quality,
       start: c.start,
       end: c.end,
@@ -2103,6 +2147,8 @@ function convertAnalysisResult(wasm) {
     chords: wasm.chords.map((c) => ({
       root: c.root,
       bass: c.bass,
+      rootName: pitchClassName(c.root),
+      bassName: pitchClassName(c.bass),
       quality: c.quality,
       start: c.start,
       end: c.end,
@@ -2251,7 +2297,7 @@ function chordFunctionalAnalysis(samples, keyRoot, keyMode, sampleRate = 22050,
 function analyze(samples, sampleRate = 22050, options = {}) {
   const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
   validateAnalysisInput("analyze", request.samples, request.sampleRate ?? 22050, request);
-  const result = requireModule14().analyze(request.samples, request.sampleRate ?? 22050);
+  const result = requireModule14().analyze(request.samples, request.sampleRate ?? 22050, request);
   return convertAnalysisResult(result);
 }
 function analyzeImpulseResponse(samples, sampleRate = 48e3, nOctaveBands = 6) {
@@ -2425,7 +2471,8 @@ var Audio = class _Audio {
    *   Node/Python surfaces).
    */
   static fromBuffer(samples, sampleRate = 48e3) {
-    return new _Audio(samples, sampleRate);
+    validateAudioBuffer(samples, sampleRate);
+    return new _Audio(samples.slice(), sampleRate);
   }
   /**
    * Create an Audio instance by decoding audio bytes in memory.
@@ -2624,7 +2671,7 @@ var Audio = class _Audio {
   rmsEnergy(frameLength = 2048, hopLength = 512) {
     return rmsEnergy(this._samples, this._sampleRate, frameLength, hopLength);
   }
-  pitchYin(frameLength = 2048, hopLength = 512, fmin = 65, fmax = 2093, threshold = 0.3, fillNa = false) {
+  pitchYin(frameLength = 2048, hopLength = 512, fmin = 65, fmax = 2093, threshold = 0.1, fillNa = false) {
     return pitchYin(
       this._samples,
       this._sampleRate,
@@ -2636,7 +2683,7 @@ var Audio = class _Audio {
       fillNa
     );
   }
-  pitchPyin(frameLength = 2048, hopLength = 512, fmin = 65, fmax = 2093, threshold = 0.3, fillNa = false) {
+  pitchPyin(frameLength = 2048, hopLength = 512, fmin = 65, fmax = 2093, threshold = 0.1, fillNa = false) {
     return pitchPyin(
       this._samples,
       this._sampleRate,
@@ -3064,6 +3111,17 @@ function meteringRmsDb(samples, sampleRate = 22050, options = {}) {
   assertSamples("meteringRmsDb", request.samples, request.validate !== false);
   return requireModule15().meteringRmsDb(request.samples, request.sampleRate ?? 22050);
 }
+function meteringSilenceRatio(samples, sampleRate = 22050, thresholdDb = -45, frameLength = 1024, hopLength = 256, options = {}) {
+  const request = samples instanceof Float32Array ? { samples, sampleRate, thresholdDb, frameLength, hopLength, ...options } : samples;
+  assertSamples("meteringSilenceRatio", request.samples, request.validate !== false);
+  return requireModule15().meteringSilenceRatio(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.thresholdDb ?? -45,
+    request.frameLength ?? 1024,
+    request.hopLength ?? 256
+  );
+}
 function meteringCrestFactorDb(samples, sampleRate = 22050, options = {}) {
   const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
   assertSamples("meteringCrestFactorDb", request.samples, request.validate !== false);
@@ -3084,11 +3142,15 @@ function meteringTruePeakDb(samples, sampleRate = 22050, oversampleFactor = 4, o
 function meteringDetectClipping(samples, sampleRate = 22050, options = {}) {
   const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
   assertSamples("meteringDetectClipping", request.samples, request.validate !== false);
+  const minRegionSamples = request.minRegionSamples ?? 1;
+  if (!Number.isInteger(minRegionSamples) || minRegionSamples < 0) {
+    throw new RangeError("meteringDetectClipping: minRegionSamples must be a non-negative integer");
+  }
   return requireModule15().meteringDetectClipping(
     request.samples,
     request.sampleRate ?? 22050,
     request.threshold ?? 0.999,
-    request.minRegionSamples ?? 1
+    minRegionSamples
   );
 }
 function meteringDynamicRange(samples, sampleRate = 22050, options = {}) {
@@ -3555,12 +3617,27 @@ var Project = class _Project {
   redo() {
     this.native.redo();
   }
+  /** Clear the undo/redo history without changing the current project state. */
+  clearHistory() {
+    this.native.clearHistory();
+  }
+  /** Cap the undo history depth (clamped to >= 1); evicts oldest entries beyond the cap. */
+  setMaxUndoDepth(depth) {
+    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, events) {
     assertProjectMidiEvents("Project.setMidiEvents", events);
     this.native.setMidiEvents(clipId, events);
   }
-  /** Import an in-memory SMF buffer; returns the first added clip id. */
+  /**
+   * Import an in-memory SMF buffer; returns the first added clip id.
+   * Malformed or partially truncated tracks are rejected instead of installing
+   * a silently shortened clip.
+   */
   importSmf(data) {
     return this.native.importSmf(data);
   }
@@ -3597,7 +3674,10 @@ var Project = class _Project {
   setProgramOnChannel(clipId, group, channel, program, bank = -1) {
     this.native.setProgramOnChannel(clipId, group, channel, program, bank);
   }
-  /** Destructively bake a MIDI-FX chain into a clip's stored MIDI events. */
+  /**
+   * Destructively bake a MIDI-FX chain into all stored events. Large clips are
+   * drained without truncation; failure leaves the original clip unchanged.
+   */
   bakeMidiFx(clipId, configJson) {
     this.native.bakeMidiFx(clipId, configJson);
   }
@@ -3607,9 +3687,9 @@ var Project = class _Project {
   }
   /**
    * Pre-flight check for hanging / unmatched notes in a MIDI clip: reports
-   * whether every note-on has a matching note-off (FIFO per channel+note).
-   * Useful before bouncing to catch a stuck note. Throws if `clipId` is unknown
-   * or not a MIDI clip.
+   * whether every note-on in the exported half-open playback window has a
+   * matching note-off (FIFO per group+channel+note). Useful before bouncing to
+   * catch a stuck note. Throws if `clipId` is unknown or not a MIDI clip.
    */
   validateMidiNotes(clipId) {
     return this.native.validateMidiNotes(clipId);
@@ -4021,6 +4101,8 @@ function panLawCode(panLaw) {
     return panLaw;
   }
   switch (panLaw) {
+    case "const3dB":
+      return 0;
     case "const4.5dB":
       return 1;
     case "const6dB":
@@ -4028,7 +4110,7 @@ function panLawCode(panLaw) {
     case "linear0dB":
       return 3;
     default:
-      return 0;
+      throw new Error(`Invalid pan law: ${panLaw}`);
   }
 }
 function panModeCode(panMode) {
@@ -4036,6 +4118,8 @@ function panModeCode(panMode) {
     return panMode;
   }
   switch (panMode) {
+    case "balance":
+      return 0;
     case "stereoPan":
     case "stereo-pan":
       return 1;
@@ -4043,17 +4127,34 @@ function panModeCode(panMode) {
     case "dual-pan":
       return 2;
     default:
-      return 0;
+      throw new Error(`Invalid pan mode: ${panMode}`);
   }
 }
 function meterTapCode(tap) {
-  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}`);
+  }
 }
 function sendTimingCode(timing) {
   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}`);
+  }
 }
 
 // src/realtime_engine.ts
@@ -4170,6 +4271,10 @@ var RealtimeEngine = class {
       options.maxValue ?? 1
     );
   }
+  /** Bind a 7/14-bit CC, RPN, or NRPN descriptor to a live parameter. */
+  bindMidiCcBinding(binding) {
+    this.native.bindMidiCcBinding(binding);
+  }
   clearMidiCcBindings() {
     this.native.clearMidiCcBindings();
   }
@@ -4294,6 +4399,7 @@ var RealtimeEngine = class {
   seekPpq(ppq, renderFrame = -1) {
     this.native.seekPpq(ppq, renderFrame);
   }
+  /** Set a finite tempo in the range (0, 100000] BPM. */
   setTempo(bpm) {
     this.native.setTempo(bpm);
   }
@@ -4348,6 +4454,7 @@ var RealtimeEngine = class {
   setLoopFromMarkers(startMarkerId, endMarkerId) {
     this.native.setLoopFromMarkers(startMarkerId, endMarkerId);
   }
+  /** Set a metronome config; click lengths are limited to one second. */
   setMetronome(config) {
     this.native.setMetronome(config);
   }
@@ -4555,6 +4662,7 @@ var RealtimeEngine = class {
   setCaptureSource(source) {
     this.native.setCaptureSource(source);
   }
+  /** Positive values delay capture relative to the punch window. */
   setRecordOffsetSamples(offsetSamples) {
     this.native.setRecordOffsetSamples(offsetSamples);
   }
@@ -4932,7 +5040,10 @@ var Mixer = class _Mixer {
     const module2 = getSonareModule();
     return new _Mixer(module2.createMixerFromSceneJson(json, sampleRate, blockSize), blockSize);
   }
-  /** Rebuild and compile the routing graph from the current scene topology. */
+  /**
+   * Rebuild and compile the routing graph without resetting its absolute
+   * automation sample position or queued strip automation.
+   */
   compile() {
     this.mixer.compile();
   }
@@ -5091,6 +5202,10 @@ var Mixer = class _Mixer {
   setVcaGroupGainDb(id, gainDb) {
     this.mixer.setVcaGroupGainDb(id, gainDb);
   }
+  /** Replace an existing VCA group's strip membership. */
+  setVcaGroupMembers(id, members) {
+    this.mixer.setVcaGroupMembers(id, members);
+  }
   /** Remove a VCA group by id. */
   removeVcaGroup(id) {
     this.mixer.removeVcaGroup(id);
@@ -5230,6 +5345,10 @@ var Mixer = class _Mixer {
     }
     return this.mixer.meterTap(stripIndex, meterTapCode(tap));
   }
+  /** Read the post-insert meter for a compiled bus, including master. */
+  busMeter(busId) {
+    return this.mixer.busMeter(busId);
+  }
   /**
    * Schedule sample-accurate fader automation on a strip.
    *
@@ -5330,6 +5449,61 @@ var Mixer = class _Mixer {
 };
 
 // src/realtime_voice_changer.ts
+function isFlatVoiceChangerPod(config) {
+  return typeof config === "object" && config !== null && "retuneSemitones" in config;
+}
+function flatVoiceChangerPodToNested(pod) {
+  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
+    }
+  };
+}
 var RealtimeVoiceChanger = class {
   constructor(config = "neutral-monitor") {
     const module2 = getSonareModule();
@@ -5342,7 +5516,8 @@ var RealtimeVoiceChanger = class {
     this.changer.reset();
   }
   setConfig(config) {
-    this.changer.setConfig(config);
+    const resolved = isFlatVoiceChangerPod(config) ? flatVoiceChangerPodToNested(config) : config;
+    this.changer.setConfig(resolved);
   }
   configJson() {
     return this.changer.configJson();
@@ -5533,7 +5708,12 @@ var EQ_PHASE_MODES = {
 var StreamingMasteringChain = class {
   constructor(config) {
     const module2 = getSonareModule();
-    this.chain = module2.createStreamingMasteringChain(config);
+    const { loudnessStaticGainDb, loudnessStaticGainPeakDb, ...chainConfig } = config;
+    this.chain = module2.createStreamingMasteringChain({
+      __flatParams: flattenChainConfig(chainConfig),
+      loudnessStaticGainDb,
+      loudnessStaticGainPeakDb
+    });
   }
   /**
    * Initialize processors for the given sample rate and block layout.
@@ -6169,6 +6349,7 @@ export {
   meteringPhaseScope,
   meteringPhaseScopeDecimated,
   meteringRmsDb,
+  meteringSilenceRatio,
   meteringSpectrum,
   meteringSpectrumFrame,
   meteringStereoCorrelation,