@libraz/libsonare 1.5.1 → 1.5.3

package/src/mixer.ts

@@ -55,9 +55,11 @@ export interface MixerRealtimeBuffer {
  */
 export class Mixer {
   private mixer: import('./sonare.js').WasmMixer;
+  private readonly blockSize: number;
 
-  private constructor(mixer: import('./sonare.js').WasmMixer) {
+  private constructor(mixer: import('./sonare.js').WasmMixer, blockSize: number) {
     this.mixer = mixer;
+    this.blockSize = blockSize;
   }
 
   /**
@@ -69,7 +71,7 @@ export class Mixer {
    */
   static fromSceneJson(json: string, sampleRate = 48000, blockSize = 512): Mixer {
     const module = getSonareModule();
-    return new Mixer(module.createMixerFromSceneJson(json, sampleRate, blockSize));
+    return new Mixer(module.createMixerFromSceneJson(json, sampleRate, blockSize), blockSize);
   }
 
   /** Rebuild and compile the routing graph from the current scene topology. */
@@ -515,7 +517,7 @@ export class Mixer {
   }
 
   /**
-   * Maximum processor tail length (samples) in the compiled mixer graph. Lazily
+   * Longest audible serial processor-tail path to the master, in samples. Lazily
    * compiles the routing graph if the topology is dirty.
    */
   tailSamples(): number {
@@ -536,6 +538,11 @@ export class Mixer {
    * master (`left`, `right`, `sampleRate`).
    */
   drainTailStereo(numSamples: number): MixerProcessResult {
+    if (!Number.isSafeInteger(numSamples) || numSamples <= 0 || numSamples > this.blockSize) {
+      throw new RangeError(
+        `Mixer.drainTailStereo: numSamples must be an integer in [1, ${this.blockSize}]`,
+      );
+    }
     return this.mixer.drainTailStereo(numSamples);
   }
 

package/src/mixing_oneshot.ts

@@ -21,6 +21,13 @@ export function mixingScenePresetJson(presetName: string): string {
   return requireModule().mixingScenePresetJson(presetName);
 }
 
+/** Inputs for the one-shot {@link mixStereo} facade. */
+export interface MixStereoRequest extends MixOptions {
+  leftChannels: Float32Array[];
+  rightChannels: Float32Array[];
+  sampleRate?: number;
+}
+
 /**
  * One-shot stereo mix of multiple strips through the routing graph + master bus.
  *
@@ -36,19 +43,32 @@ export function mixingScenePresetJson(presetName: string): string {
  * @param sampleRate - Sample rate in Hz
  * @param options - Per-strip mix options (trim, fader, pan, width, mute)
  */
+export function mixStereo(request: MixStereoRequest): MixResult;
 export function mixStereo(
   leftChannels: Float32Array[],
   rightChannels: Float32Array[],
+  sampleRate?: number,
+  options?: MixOptions,
+): MixResult;
+export function mixStereo(
+  leftChannels: Float32Array[] | MixStereoRequest,
+  rightChannels?: Float32Array[],
   sampleRate = 48000,
   options: MixOptions = {},
 ): MixResult {
-  if (leftChannels.length === 0 || leftChannels.length !== rightChannels.length) {
+  const request = Array.isArray(leftChannels)
+    ? { leftChannels, rightChannels: rightChannels ?? [], sampleRate, ...options }
+    : leftChannels;
+  if (
+    request.leftChannels.length === 0 ||
+    request.leftChannels.length !== request.rightChannels.length
+  ) {
     throw new Error('leftChannels and rightChannels must have the same non-zero length.');
   }
   return requireModule().mixStereo(
-    leftChannels,
-    rightChannels,
-    sampleRate,
-    options as Record<string, unknown>,
+    request.leftChannels,
+    request.rightChannels,
+    request.sampleRate ?? 48000,
+    request as unknown as Record<string, unknown>,
   );
 }

package/src/module_state.ts

@@ -149,7 +149,7 @@ function wrapModuleErrors(raw: SonareModule): SonareModule {
       },
       construct(t, args, newTarget) {
         try {
-          return wrapNativeObject(Reflect.construct(t, args as unknown[], newTarget));
+          return wrapNativeObject(Reflect.construct(t, args as unknown[], newTarget)) as object;
         } catch (error) {
           return convert(error) as object;
         }

package/src/project_class.ts

@@ -32,6 +32,7 @@ import type {
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
+  ProjectTempoCandidate,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
   ProjectTrackDesc,
@@ -504,14 +505,24 @@ export class Project {
     return this.native.validateMidiNotes(clipId);
   }
 
-  /** Detect tempo from a mono buffer and install it; returns the primary BPM. */
-  autoTempo(audio: Float32Array, sampleRate: number): number {
-    return this.native.autoTempo(audio, sampleRate);
+  /** Return ranked tempo-octave and detected-meter candidates without editing. */
+  analyzeTempo(audio: Float32Array, sampleRate: number): ProjectTempoCandidate[] {
+    return this.native.analyzeTempo(audio, sampleRate);
   }
 
-  /** Snap a PPQ coordinate to the nearest beat of the project grid. */
-  snapToGrid(ppq: number, strength = 1.0): number {
-    return this.native.snapToGrid(ppq, strength);
+  /** Detect and install a ranked tempo candidate; optionally apply detected meter. */
+  autoTempo(
+    audio: Float32Array,
+    sampleRate: number,
+    candidateIndex = 0,
+    applyTimeSignatures = false,
+  ): number {
+    return this.native.autoTempo(audio, sampleRate, candidateIndex, applyTimeSignatures);
+  }
+
+  /** Snap to a bar (`division=0`), beat (`1`), or beat subdivision (`2+`). */
+  snapToGrid(ppq: number, strength = 1.0, division = 1): number {
+    return this.native.snapToGrid(ppq, strength, division);
   }
 
   /** Compile the project into a renderable timeline, surfacing diagnostics. */

package/src/project_internal.ts

@@ -1,6 +1,7 @@
 import { getSonareModule } from './module_state';
 import type {
   BuiltinSynthBinding,
+  ProjectAssistSidecar,
   ProjectAutomationPoint,
   ProjectBounceOptions,
   ProjectChordSymbol,
@@ -20,6 +21,7 @@ import type {
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
+  ProjectTempoCandidate,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
   ProjectTrackKind,
@@ -75,8 +77,14 @@ export interface WasmProject {
   bakeMidiFx: (clipId: number, configJson: string) => void;
   setMidiFx: (clipId: number, configJson: string) => void;
   validateMidiNotes: (clipId: number) => ProjectNotePairValidation;
-  autoTempo: (audio: Float32Array, sampleRate: number) => number;
-  snapToGrid: (ppq: number, strength: number) => number;
+  analyzeTempo: (audio: Float32Array, sampleRate: number) => ProjectTempoCandidate[];
+  autoTempo: (
+    audio: Float32Array,
+    sampleRate: number,
+    candidateIndex: number,
+    applyTimeSignatures: boolean,
+  ) => number;
+  snapToGrid: (ppq: number, strength: number, division: number) => number;
   compile: () => ProjectCompileResult;
   bounce: (options: ProjectBounceOptions) => Float32Array;
   bounceWithBuiltinInstrument: (

package/src/project_types.ts

@@ -362,8 +362,22 @@ export interface ProjectLoopRecordingResult {
 export type ProjectLoopMode = 'off' | 'loop' | 0 | 1;
 export type ProjectWarpMode = 'off' | 'repitch' | 'tempo-sync' | 0 | 1 | 2;
 
-/** Automation breakpoint interpolation for {@link ProjectAutomationPoint}. */
-export type ProjectAutomationCurve = 'linear' | 'exponential' | 'hold' | 'scurve' | 0 | 1 | 2 | 3;
+/**
+ * Automation breakpoint interpolation for {@link ProjectAutomationPoint}.
+ *
+ * `'s-curve'` is the canonical spelling, matching the Node engine and the mixer
+ * automation types. The legacy `'scurve'` remains accepted for compatibility.
+ */
+export type ProjectAutomationCurve =
+  | 'linear'
+  | 'exponential'
+  | 'hold'
+  | 's-curve'
+  | 'scurve'
+  | 0
+  | 1
+  | 2
+  | 3;
 
 /** One automation breakpoint accepted by the automation-lane edit ops. */
 export interface ProjectAutomationPoint {
@@ -405,6 +419,15 @@ export interface ProjectTimeSignatureSegment {
   denominator: number;
 }
 
+/** A ranked primary/half/double tempo hypothesis returned by {@link Project.analyzeTempo}. */
+export interface ProjectTempoCandidate {
+  bpm: number;
+  confidence: number;
+  label: 'primary' | 'half' | 'double';
+  timeSignatureCount: number;
+  timeSignature: ProjectTimeSignatureSegment;
+}
+
 /** Key segment for {@link Project.annotateKeys}. */
 export interface ProjectKeySegment {
   startPpq: number;

package/src/public_types_mastering.ts

@@ -143,14 +143,65 @@ export interface MasteringResult {
 
 export type MasteringProcessorParams = Record<string, number | boolean>;
 
+/**
+ * Nested mastering-chain configuration. A boolean toggles a module/processor's
+ * `enabled` flag; setting any field implicitly enables its module unless
+ * `enabled: false` is also given.
+ *
+ * Exception — color stages as `masterAudio` overrides: the `saturation.tape`
+ * and `saturation.exciter` stages are engaged from an override only when you
+ * pass `enabled: true` explicitly. On a preset where they are off, adjusting a
+ * parameter alone (e.g. `saturation: { tape: { driveDb: 6 } }`) has no audible
+ * effect; use `saturation: { tape: { enabled: true, driveDb: 6 } }`.
+ */
 export interface MasteringChainConfig {
   repair?: {
-    denoise?: boolean;
+    /** `boolean` is retained as a deprecated shorthand for `{ enabled }`. */
+    denoise?:
+      | boolean
+      | {
+          enabled?: boolean;
+          nFft?: number;
+          hopLength?: number;
+          ddAlpha?: number;
+          gainFloor?: number;
+          overSubtraction?: number;
+          spectralFloor?: number;
+          noiseEstimationQuantile?: number;
+          speechPresenceGain?: boolean;
+          gainSmoothing?: boolean;
+        };
     nFft?: number;
     hopLength?: number;
     ddAlpha?: number;
     gainFloor?: number;
+    declip?: {
+      enabled?: boolean;
+      clipThreshold?: number;
+      lpcOrder?: number;
+      iterations?: number;
+      lpcBlend?: number;
+    };
+    decrackle?: {
+      enabled?: boolean;
+      threshold?: number;
+      /** 0 = median, 1 = wavelet shrinkage. */
+      mode?: number;
+      levels?: number;
+    };
+    dehum?: {
+      enabled?: boolean;
+      fundamentalHz?: number;
+      harmonics?: number;
+      q?: number;
+      adaptive?: boolean;
+      searchRangeHz?: number;
+      adaptation?: number;
+      frameSize?: number;
+      pllBandwidth?: number;
+    };
     declick?: {
+      enabled?: boolean;
       threshold?: number;
       neighborRatio?: number;
       maxClickSamples?: number;
@@ -158,6 +209,7 @@ export interface MasteringChainConfig {
       residualRatio?: number;
     };
     dereverb?: {
+      enabled?: boolean;
       threshold?: number;
       attenuation?: number;
       nFft?: number;
@@ -173,11 +225,20 @@ export interface MasteringChainConfig {
     };
   };
   eq?: {
+    /** Canonical nested tilt stage. */
+    tilt?: {
+      enabled?: boolean;
+      tiltDb?: number;
+      pivotHz?: number;
+    };
+    /** @deprecated Use `eq.tilt.tiltDb`. */
     tiltDb?: number;
+    /** @deprecated Use `eq.tilt.pivotHz`. */
     pivotHz?: number;
   };
   dynamics?: {
     compressor?: {
+      enabled?: boolean;
       thresholdDb?: number;
       ratio?: number;
       attackMs?: number;
@@ -187,6 +248,7 @@ export interface MasteringChainConfig {
       autoMakeup?: boolean;
     };
     deesser?: {
+      enabled?: boolean;
       frequencyHz?: number;
       thresholdDb?: number;
       ratio?: number;
@@ -196,6 +258,7 @@ export interface MasteringChainConfig {
       bandpassQ?: number;
     };
     transientShaper?: {
+      enabled?: boolean;
       attackGainDb?: number;
       sustainGainDb?: number;
       fastAttackMs?: number;
@@ -208,6 +271,7 @@ export interface MasteringChainConfig {
       lookaheadMs?: number;
     };
     multibandComp?: {
+      enabled?: boolean;
       lowCutoffHz?: number;
       highCutoffHz?: number;
       lowThresholdDb?: number;
@@ -226,6 +290,7 @@ export interface MasteringChainConfig {
   };
   saturation?: {
     tape?: {
+      enabled?: boolean;
       driveDb?: number;
       saturation?: number;
       hysteresis?: number;
@@ -236,6 +301,7 @@ export interface MasteringChainConfig {
       gapLoss?: number;
     };
     exciter?: {
+      enabled?: boolean;
       frequencyHz?: number;
       driveDb?: number;
       amount?: number;
@@ -245,6 +311,7 @@ export interface MasteringChainConfig {
   };
   spectral?: {
     airBand?: {
+      enabled?: boolean;
       amount?: number;
       shelfFrequencyHz?: number;
       dynamicThresholdDb?: number;
@@ -253,17 +320,20 @@ export interface MasteringChainConfig {
   };
   stereo?: {
     imager?: {
+      enabled?: boolean;
       width?: number;
       outputGainDb?: number;
       decorrelationAmount?: number;
       preserveEnergy?: boolean;
     };
     monoMaker?: {
+      enabled?: boolean;
       amount?: number;
     };
   };
   maximizer?: {
     truePeakLimiter?: {
+      enabled?: boolean;
       ceilingDb?: number;
       lookaheadMs?: number;
       releaseMs?: number;
@@ -272,9 +342,12 @@ export interface MasteringChainConfig {
     };
   };
   loudness?: {
+    enabled?: boolean;
     targetLufs?: number;
     ceilingDb?: number;
     truePeakOversample?: number;
+    releaseMs?: number;
+    applyGainAtInputRate?: boolean;
   };
 }
 
@@ -307,11 +380,38 @@ export interface StreamingMasteringChainConfig extends MasteringChainConfig {
   loudnessStaticGainPeakDb?: number;
 }
 
-export interface MasteringChainResult extends MasteringResult {
+/** Gain reduction reported by a single dynamics/maximizer chain stage. */
+export interface StageGainReduction {
+  /** Stage identifier, e.g. `"dynamics.compressor"`. */
+  stage: string;
+  /**
+   * Most recent (typically last-block) gain reduction in dB (negative or
+   * zero); for multiband stages it is the most-reduced band.
+   */
+  gainReductionDb: number;
+}
+
+export interface MasteringChainResult {
+  /** Latency-compensated offline output; no separate latency field is reported. */
+  samples: Float32Array;
+  sampleRate: number;
+  inputLufs: number;
+  outputLufs: number;
+  appliedGainDb: number;
   stages: string[];
+  /**
+   * ITU-R BS.1770-4 true peak of the output (dBTP), measured with the chain's
+   * configured loudness true-peak oversample factor (default 4x). Lets callers
+   * verify a preset ceiling was met without a second oversampled scan.
+   */
+  outputTruePeakDbtp: number;
+  /** EBU Tech 3342 Loudness Range of the output (LU). */
+  outputLra: number;
+  /** Per-stage gain reductions for the dynamics/maximizer stages (a subset of `stages`). */
+  stageGainReductions: StageGainReduction[];
 }
 
-export interface MasteringStereoChainResult {
+export interface MasteringChainStereoResult {
   left: Float32Array;
   right: Float32Array;
   sampleRate: number;
@@ -319,9 +419,19 @@ export interface MasteringStereoChainResult {
   outputLufs: number;
   appliedGainDb: number;
   stages: string[];
-  latencySamples?: number;
+  /** See {@link MasteringChainResult} for field semantics. */
+  outputTruePeakDbtp: number;
+  outputLra: number;
+  stageGainReductions: StageGainReduction[];
 }
 
+/**
+ * @deprecated Use {@link MasteringChainStereoResult}. Retained as an alias for
+ * source compatibility; the canonical name matches the Node and Python
+ * bindings (`MasteringChainStereoResult`).
+ */
+export type MasteringStereoChainResult = MasteringChainStereoResult;
+
 export interface MasteringStereoResult {
   left: Float32Array;
   right: Float32Array;

package/src/public_types_music.ts

@@ -140,6 +140,7 @@ export interface KeyCandidate {
 export interface ChordDetectionOptions extends ValidateOptions {
   minDuration?: number;
   smoothingWindow?: number;
+  /** Final-template correlation threshold in [0, 1]; below it emits Unknown / N.C. */
   threshold?: number;
   useTriadsOnly?: boolean;
   nFft?: number;

package/src/public_types_spectral.ts

@@ -36,6 +36,13 @@ export interface NoteStretchOptions {
   stretchRatio?: number;
 }
 
+/** Options for `noteMove`. */
+export interface NoteMoveOptions {
+  onsetSample?: number;
+  offsetSample?: number;
+  targetOnsetSample?: number;
+}
+
 /** How a `spectralEdit` region op modifies the masked bins. */
 export type SpectralEditMode = 'gain' | 'attenuate' | 'mute' | 'heal';