@libraz/libsonare 1.5.4 → 1.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "type": "module",
   "packageManager": "yarn@4.15.0",
   "description": "Audio analysis, mastering, mixing, and MIDI synthesis in WebAssembly",

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/effects_transform.ts

@@ -238,6 +238,10 @@ export function pitchShift(
 /**
  * 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
@@ -279,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)
@@ -354,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)
@@ -411,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;
@@ -431,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,
   );
 }
@@ -454,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,
   );
 }
@@ -464,7 +470,7 @@ export function noteMove(
  *
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz (default: 22050)
- * @param targetDb - Target peak level in dB (default: 0 dB = full scale)
+ * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale)
  * @returns Normalized audio
  */
 export function normalize(request: NormalizeRequest): Float32Array;

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

@@ -98,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(
@@ -140,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,
+  );
 }
 
 /**
@@ -307,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;
@@ -328,7 +338,7 @@ export function vqt(
   fmin = 32.70319566257483,
   nBins = 84,
   binsPerOctave = 12,
-  gamma = 0,
+  gamma = -1,
   options: GuardedOptions = {},
 ): CqtResult {
   if (!(samples instanceof Float32Array)) {
@@ -348,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);
 }
 
@@ -465,7 +472,7 @@ export function vqtToAudio(
   hopLength = 512,
   fmin = 32.70319566257483,
   binsPerOctave = 12,
-  gamma = 0,
+  gamma = -1,
   nIter = 32,
   options: GuardedOptions = {},
 ): Float32Array {
@@ -497,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,
@@ -544,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

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);
 }

package/src/feature_spectrogram.ts

@@ -34,6 +34,7 @@ export interface ChromaSpectrogramRequest extends GuardedOptions {
   sampleRate?: number;
   hopLength?: number;
   nChroma?: number;
+  binsPerOctave?: number;
 }
 
 export interface MelSpectrogramRequest extends SpectrogramRequest {
@@ -53,6 +54,8 @@ export interface MfccToMelRequest extends GuardedOptions {
   nMfcc: number;
   nFrames: number;
   nMels?: number;
+  /** Lifter used by the forward MFCC transform; zero means no liftering. */
+  lifter?: number;
 }
 
 /** Canonical request form for reconstruction from a Mel power spectrogram. */
@@ -262,6 +265,7 @@ export function chromaCens(
   sampleRate?: number,
   hopLength?: number,
   nChroma?: number,
+  binsPerOctave?: number,
   options?: GuardedOptions,
 ): ChromaResult;
 export function chromaCens(
@@ -269,6 +273,7 @@ export function chromaCens(
   sampleRate = 22050,
   hopLength = 512,
   nChroma = 12,
+  binsPerOctave = 36,
   options: GuardedOptions = {},
 ): ChromaResult {
   if (!(samples instanceof Float32Array)) {
@@ -278,12 +283,16 @@ export function chromaCens(
       request.sampleRate,
       request.hopLength,
       request.nChroma,
+      request.binsPerOctave,
       request,
     );
   }
   validateSpectrogramSamples('chromaCens', samples, sampleRate, options);
-  validatePositiveIntegers('chromaCens', { hopLength, nChroma });
-  return requireModule().chromaCens(samples, sampleRate, hopLength, nChroma);
+  validatePositiveIntegers('chromaCens', { hopLength, nChroma, binsPerOctave });
+  if (binsPerOctave % nChroma !== 0) {
+    throw new RangeError('chromaCens: binsPerOctave must be a multiple of nChroma');
+  }
+  return requireModule().chromaCens(samples, sampleRate, hopLength, nChroma, binsPerOctave);
 }
 
 /**
@@ -301,6 +310,7 @@ export function chromaCqt(
   sampleRate?: number,
   hopLength?: number,
   nChroma?: number,
+  binsPerOctave?: number,
   options?: GuardedOptions,
 ): ChromaResult;
 export function chromaCqt(
@@ -308,6 +318,7 @@ export function chromaCqt(
   sampleRate = 22050,
   hopLength = 512,
   nChroma = 12,
+  binsPerOctave = 36,
   options: GuardedOptions = {},
 ): ChromaResult {
   if (!(samples instanceof Float32Array)) {
@@ -317,12 +328,16 @@ export function chromaCqt(
       request.sampleRate,
       request.hopLength,
       request.nChroma,
+      request.binsPerOctave,
       request,
     );
   }
   validateSpectrogramSamples('chromaCqt', samples, sampleRate, options);
-  validatePositiveIntegers('chromaCqt', { hopLength, nChroma });
-  return requireModule().chromaCqt(samples, sampleRate, hopLength, nChroma);
+  validatePositiveIntegers('chromaCqt', { hopLength, nChroma, binsPerOctave });
+  if (binsPerOctave % nChroma !== 0) {
+    throw new RangeError('chromaCqt: binsPerOctave must be a multiple of nChroma');
+  }
+  return requireModule().chromaCqt(samples, sampleRate, hopLength, nChroma, binsPerOctave);
 }
 
 /**
@@ -664,6 +679,7 @@ export function mfccToMel(
   nMfcc: number,
   nFrames: number,
   nMels?: number,
+  lifter?: number,
   options?: GuardedOptions,
 ): MelPowerResult;
 export function mfccToMel(
@@ -671,6 +687,7 @@ export function mfccToMel(
   nMfcc = 0,
   nFrames = 0,
   nMels = 128,
+  lifter = 0,
   options: GuardedOptions = {},
 ): MelPowerResult {
   if (!(mfccCoefficients instanceof Float32Array)) {
@@ -680,6 +697,7 @@ export function mfccToMel(
       request.nMfcc,
       request.nFrames,
       request.nMels,
+      request.lifter,
       request,
     );
   }
@@ -693,7 +711,7 @@ export function mfccToMel(
     options,
   );
   validatePositiveIntegers('mfccToMel', { nMels });
-  return requireModule().mfccToMel(mfccCoefficients, nMfcc, nFrames, nMels);
+  return requireModule().mfccToMel(mfccCoefficients, nMfcc, nFrames, nMels, lifter);
 }
 
 /**
@@ -726,6 +744,7 @@ export function mfccToAudio(
   fmax?: number,
   nIter?: number,
   htk?: boolean,
+  lifter?: number,
   options?: GuardedOptions,
 ): Float32Array;
 export function mfccToAudio(
@@ -740,6 +759,7 @@ export function mfccToAudio(
   fmax = 0,
   nIter = 32,
   htk = false,
+  lifter = 0,
   options: GuardedOptions = {},
 ): Float32Array {
   if (!(mfccCoefficients instanceof Float32Array)) {
@@ -756,6 +776,7 @@ export function mfccToAudio(
       request.fmax,
       request.nIter,
       request.htk,
+      request.lifter,
       request,
     );
   }
@@ -783,6 +804,7 @@ export function mfccToAudio(
     fmax,
     nIter,
     htk,
+    lifter,
   );
 }
 

package/src/index.ts

@@ -312,6 +312,7 @@ export type {
   MeteringDynamicRangeOptions,
   MeteringDynamicRangeRequest,
   MeteringSamplesRequest,
+  MeteringSilenceRatioRequest,
   MeteringSpectrumFrameRequest,
   MeteringSpectrumRequest,
   MeteringStereoDecimatedRequest,
@@ -336,6 +337,7 @@ export {
   meteringPhaseScope,
   meteringPhaseScopeDecimated,
   meteringRmsDb,
+  meteringSilenceRatio,
   meteringSpectrum,
   meteringSpectrumFrame,
   meteringStereoCorrelation,
@@ -522,6 +524,7 @@ export type {
   DetectKeyRequest,
   DynamicsAnalysisResult,
   EstimateRoomRequest,
+  MusicAnalyzeRequest,
   RhythmAnalysisResult,
   RoomMorphRequest,
   SamplesRequest,

package/src/mastering_core.ts

@@ -152,6 +152,8 @@ export interface MasteringInsertParamInfo {
   id: number;
   /** Whether the param can be changed live from the audio thread. */
   rtSafe: boolean;
+  /** Physical unit when the parameter is not unitless. */
+  unit?: string;
 }
 
 /**

package/src/metering.ts

@@ -128,6 +128,43 @@ export function meteringRmsDb(
   return requireModule().meteringRmsDb(request.samples, request.sampleRate ?? 22050);
 }
 
+export interface MeteringSilenceRatioRequest extends MeteringSamplesRequest {
+  thresholdDb?: number;
+  frameLength?: number;
+  hopLength?: number;
+}
+
+export function meteringSilenceRatio(request: MeteringSilenceRatioRequest): number;
+export function meteringSilenceRatio(
+  samples: Float32Array,
+  sampleRate?: number,
+  thresholdDb?: number,
+  frameLength?: number,
+  hopLength?: number,
+  options?: ValidateOptions,
+): number;
+export function meteringSilenceRatio(
+  samples: Float32Array | MeteringSilenceRatioRequest,
+  sampleRate = 22050,
+  thresholdDb = -45,
+  frameLength = 1024,
+  hopLength = 256,
+  options: ValidateOptions = {},
+): number {
+  const request =
+    samples instanceof Float32Array
+      ? { samples, sampleRate, thresholdDb, frameLength, hopLength, ...options }
+      : samples;
+  assertSamples('meteringSilenceRatio', request.samples, request.validate !== false);
+  return requireModule().meteringSilenceRatio(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.thresholdDb ?? -45,
+    request.frameLength ?? 1024,
+    request.hopLength ?? 256,
+  );
+}
+
 export function meteringCrestFactorDb(request: MeteringSamplesRequest): number;
 export function meteringCrestFactorDb(
   samples: Float32Array,
@@ -206,16 +243,20 @@ export function meteringDetectClipping(
 ): ClippingReport {
   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 requireModule().meteringDetectClipping(
     request.samples,
     request.sampleRate ?? 22050,
     request.threshold ?? 0.999,
-    request.minRegionSamples ?? 1,
+    minRegionSamples,
   );
 }
 
 /**
- * Sliding-window dynamic range. Pass 0 for window/hop to use the library
+ * Sliding-window dynamic range for mono audio. Pass 0 for window/hop to use the library
  * default (window=3 s, hop=1 s). The percentiles use a NEGATIVE sentinel for
  * "use the library default" (low=0.10, high=0.95) because 0 is a literal 0th
  * percentile; omitted percentiles therefore default to -1.
@@ -354,7 +395,7 @@ export interface WaveformPeaksReport {
   samplesPerBucket: number;
 }
 
-/** Pearson correlation in [-1, 1] between two equal-length channels. */
+/** Uncentered correlation (cosine similarity) in [-1, 1] between equal-length channels. */
 export function meteringStereoCorrelation(request: MeteringStereoRequest): number;
 export function meteringStereoCorrelation(
   left: Float32Array,
@@ -561,7 +602,7 @@ export function meteringPhaseScopeDecimated(
 }
 
 /**
- * Welch-averaged magnitude / power / dB spectrum over the WHOLE signal (split
+ * Welch-averaged magnitude / power / dB spectrum over the WHOLE mono signal (split
  * into Hann-windowed, 50%-overlapping `nFft`-length frames whose power spectra
  * are averaged). For a true single-frame snapshot, use
  * {@link meteringSpectrumFrame}.

package/src/mixer.ts

@@ -74,7 +74,10 @@ export class Mixer {
     return new Mixer(module.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(): void {
     this.mixer.compile();
   }
@@ -261,6 +264,11 @@ export class Mixer {
     this.mixer.setVcaGroupGainDb(id, gainDb);
   }
 
+  /** Replace an existing VCA group's strip membership. */
+  setVcaGroupMembers(id: string, members: string[]): void {
+    this.mixer.setVcaGroupMembers(id, members);
+  }
+
   /** Remove a VCA group by id. */
   removeVcaGroup(id: string): void {
     this.mixer.removeVcaGroup(id);
@@ -427,6 +435,11 @@ export class Mixer {
     return this.mixer.meterTap(stripIndex, meterTapCode(tap));
   }
 
+  /** Read the post-insert meter for a compiled bus, including master. */
+  busMeter(busId: string): MixMeterSnapshot {
+    return this.mixer.busMeter(busId);
+  }
+
   /**
    * Schedule sample-accurate fader automation on a strip.
    *