@libraz/libsonare 1.7.0 → 1.7.2

package/package.json

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

package/src/_chain_config.ts

@@ -6,7 +6,12 @@ type ChainSection = { [key: string]: number | boolean | ChainSection | undefined
  * Flattens a nested {@link MasteringChainConfig} into the dot-notation
  * `{ "module.processor.param": value }` map the core consumes. Internal helper
  * shared by the mastering-chain / master-audio entry points. The core owns
- * legacy flat-key aliases, so this remains a structural flattening step.
+ * legacy leaf-name aliases, so this remains a structural flattening step.
+ *
+ * A key the caller already wrote in dot notation carries through untouched, so
+ * both spellings a {@link MasteringChainConfig} accepts reach the core as the
+ * same parameter — matching what the Python binding documents. An unknown key
+ * in either spelling is rejected by the core, not here.
  */
 export function flattenChainConfig(config: MasteringChainConfig): Record<string, number | boolean> {
   const out: Record<string, number | boolean> = {};

package/src/effects_mastering.ts

@@ -41,12 +41,16 @@ export type {
   MasteringRealtimeCost,
   MasteringSamplesParamsRequest,
   MasteringStereoAnalyzeRequest,
+  MasteringStereoParamsRequest,
   MasteringStreamingPreviewRequest,
+  MasteringStreamingPreviewStereoRequest,
 } from './mastering_core';
 export {
   mastering,
   masteringAssistantSuggest,
+  masteringAssistantSuggestStereo,
   masteringAudioProfile,
+  masteringAudioProfileStereo,
   masteringInsertNames,
   masteringInsertParamInfo,
   masteringInsertParamNames,
@@ -61,6 +65,7 @@ export {
   masteringStereoAnalysisNames,
   masteringStereoAnalyze,
   masteringStreamingPreview,
+  masteringStreamingPreviewStereo,
 } from './mastering_core';
 export type {
   CompressorDetector,

package/src/effects_transform.ts

@@ -6,6 +6,7 @@ import type {
   PitchCorrectOptions,
   SpectralEditOptions,
   SpectralRegionOp,
+  VoicedFlags,
 } from './public_types';
 import type { ValidateOptions } from './validation';
 import { assertSampleRate, assertSamples } from './validation';
@@ -14,6 +15,18 @@ function requireModule() {
   return getSonareModule();
 }
 
+// The embind layer reads the companion voicing array as Float32Array. A flag is
+// a decision, not a magnitude: collapse to 1/0 on truthiness, which is the same
+// reduction the Node facade applies, so both surfaces agree on every accepted
+// input type.
+function toVoicedFloat32(voiced: VoicedFlags): Float32Array {
+  const out = new Float32Array(voiced.length);
+  for (let index = 0; index < voiced.length; index += 1) {
+    out[index] = voiced[index] ? 1 : 0;
+  }
+  return out;
+}
+
 function resolveEffectFftOptions(
   fnName: string,
   nFft: unknown,
@@ -114,7 +127,7 @@ export interface PitchCorrectToMidiTimevaryingRequest extends ValidateOptions {
   targetMidi: number;
   sampleRate?: number;
   hopLength?: number;
-  voiced?: Int32Array;
+  voiced?: VoicedFlags;
   voicedProb?: Float32Array;
 }
 
@@ -423,16 +436,18 @@ export function pitchCorrectToMidi(
  * Unlike {@link pitchCorrectToMidi} (a single constant transpose), this follows
  * 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;
+ * flattened. `voiced` (truthy = voiced) and `voicedProb` ([0,1]) are optional;
  * omitting them treats every frame as voiced. An `f0Hz` NaN is accepted only
- * when the corresponding `voiced` entry is zero, matching pYIN output.
+ * when the corresponding `voiced` entry is falsy, matching pYIN output. The
+ * `voicedFlag` / `voicedProb` arrays of a {@link PitchResult} can be passed
+ * through directly.
  *
  * @param samples - Audio samples (mono, float32)
  * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
  * @param targetMidi - Desired MIDI note number
  * @param sampleRate - Sample rate in Hz
  * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
- * @param voiced - Optional per-frame voiced flags (non-zero = voiced)
+ * @param voiced - Optional per-frame voiced flags (truthy = voiced)
  * @param voicedProb - Optional per-frame voicing probability in [0, 1]
  * @returns Pitch-corrected audio
  */
@@ -445,7 +460,7 @@ export function pitchCorrectToMidiTimevarying(
   targetMidi: number,
   sampleRate?: number,
   hopLength?: number,
-  voiced?: Int32Array,
+  voiced?: VoicedFlags,
   voicedProb?: Float32Array,
   options?: ValidateOptions,
 ): Float32Array;
@@ -455,7 +470,7 @@ export function pitchCorrectToMidiTimevarying(
   targetMidi?: number,
   sampleRate = 22050,
   hopLength = 512,
-  voiced?: Int32Array,
+  voiced?: VoicedFlags,
   voicedProb?: Float32Array,
   options: ValidateOptions = {},
 ): Float32Array {
@@ -479,9 +494,7 @@ export function pitchCorrectToMidiTimevarying(
   if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
     throw new RangeError('pitchCorrectToMidiTimevarying: voicedProb length must match f0Hz length');
   }
-  // The embind layer reads the companion arrays as Float32Array (voiced uses
-  // 0.0/1.0); convert here so a single native conversion path suffices.
-  const voicedF32 = request.voiced ? Float32Array.from(request.voiced) : undefined;
+  const voicedF32 = request.voiced ? toVoicedFloat32(request.voiced) : undefined;
   return requireModule().pitchCorrectToMidiTimevarying(
     request.samples,
     request.sampleRate ?? 22050,
@@ -536,11 +549,9 @@ export function pitchCorrectTimevarying(
   if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
     throw new RangeError('pitchCorrectTimevarying: voicedProb length must match f0Hz length');
   }
-  // The embind layer reads the companion arrays as Float32Array (voiced uses
-  // 0.0/1.0); convert here so a single native conversion path suffices.
   const nativeOptions = {
     ...request,
-    voiced: request.voiced ? Float32Array.from(request.voiced) : undefined,
+    voiced: request.voiced ? toVoicedFloat32(request.voiced) : undefined,
   };
   return requireModule().pitchCorrectTimevarying(
     request.samples,

package/src/index.ts

@@ -78,7 +78,9 @@ export type {
   MasteringRepairTrimSilenceRequest,
   MasteringSamplesParamsRequest,
   MasteringStereoAnalyzeRequest,
+  MasteringStereoParamsRequest,
   MasteringStreamingPreviewRequest,
+  MasteringStreamingPreviewStereoRequest,
   MixStereoRequest,
   TransientShaperOptions,
   TrimSilenceMode,
@@ -97,7 +99,9 @@ export {
   masterAudioWithProgress,
   mastering,
   masteringAssistantSuggest,
+  masteringAssistantSuggestStereo,
   masteringAudioProfile,
+  masteringAudioProfileStereo,
   masteringChain,
   masteringChainStereo,
   masteringChainStereoWithProgress,
@@ -127,6 +131,7 @@ export {
   masteringStereoAnalysisNames,
   masteringStereoAnalyze,
   masteringStreamingPreview,
+  masteringStreamingPreviewStereo,
   mixingScenePresetJson,
   mixingScenePresetNames,
   mixStereo,
@@ -375,6 +380,7 @@ export type {
 } from './metering';
 export {
   meteringCrestFactorDb,
+  meteringCrestFactorDbStereo,
   meteringDcOffset,
   meteringDetectClipping,
   meteringDynamicRange,
@@ -432,6 +438,9 @@ export type {
   ProjectMarker,
   ProjectMidiClipResult,
   ProjectMidiEvent,
+  ProjectMidiFxBakeRequest,
+  ProjectMidiFxBakeResult,
+  ProjectMidiFxPreviewRequest,
   ProjectNotePairValidation,
   ProjectSource,
   ProjectTrack,
@@ -566,6 +575,7 @@ export type {
   TempogramMode,
   Timbre,
   TimeSignature,
+  VoicedFlags,
   VoicePresetId,
 } from './public_types';
 export {

package/src/mastering_core.ts

@@ -77,6 +77,22 @@ export interface MasteringStreamingPreviewRequest {
   platforms?: StreamingPlatform[];
 }
 
+/** Canonical request form for the stereo analysis entry points. */
+export interface MasteringStereoParamsRequest {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+  params?: MasteringProcessorParams;
+}
+
+/** Canonical request form for the stereo streaming-platform preview. */
+export interface MasteringStreamingPreviewStereoRequest {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+  platforms?: StreamingPlatform[];
+}
+
 /**
  * Apply mastering loudness normalization with a true-peak ceiling.
  *
@@ -479,3 +495,57 @@ export function masteringStreamingPreview(
     request.platforms ?? [],
   );
 }
+
+/**
+ * Suggest a mastering chain for a stereo pair, as shared JSON.
+ *
+ * Profiles through {@link masteringAudioProfileStereo}, so the loudness stage
+ * of the suggestion is built on the channel-summed program rather than a
+ * downmix that reads roughly 6 dB low.
+ */
+export function masteringAssistantSuggestStereo(request: MasteringStereoParamsRequest): string {
+  return requireModule().masteringAssistantSuggestStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.params ?? {},
+  );
+}
+
+/**
+ * Mastering assistant profile of a stereo pair, as shared JSON.
+ *
+ * Only the `loudness` block is measured from the two channels: integrated LUFS
+ * and LRA come from the channel-summed program and the true peak is the larger
+ * of the two. The spectral, dynamics and tempo fields describe shape and timing
+ * rather than absolute level and are measured on the downmix, which keeps them
+ * comparable with {@link masteringAudioProfile}.
+ */
+export function masteringAudioProfileStereo(request: MasteringStereoParamsRequest): string {
+  return requireModule().masteringAudioProfileStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.params ?? {},
+  );
+}
+
+/**
+ * Preview streaming-platform normalization for a stereo pair, as shared JSON.
+ *
+ * Measures the integrated loudness with BS.1770 channel summing and reports the
+ * larger of the two channel true peaks. Passing a `0.5 * (left + right)` downmix
+ * to {@link masteringStreamingPreview} instead reads roughly 6 dB low on
+ * decorrelated material, and both the normalization gain and the ceiling-risk
+ * flag follow from that measurement.
+ */
+export function masteringStreamingPreviewStereo(
+  request: MasteringStreamingPreviewStereoRequest,
+): string {
+  return requireModule().masteringStreamingPreviewStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.platforms ?? [],
+  );
+}

package/src/metering.ts

@@ -186,6 +186,24 @@ export function meteringCrestFactorDb(
   return requireModule().meteringCrestFactorDb(request.samples, request.sampleRate ?? 22050);
 }
 
+/**
+ * Crest factor in dB across both channels of a stereo pair.
+ *
+ * Takes the peak across both channels and the RMS over both together. An
+ * out-of-phase pair cancels in the `0.5 * (left + right)` downmix
+ * {@link meteringCrestFactorDb} would need, which understates its RMS and so
+ * overstates the crest factor.
+ */
+export function meteringCrestFactorDbStereo(request: MeteringStereoRequest): number {
+  assertSamples('meteringCrestFactorDbStereo', request.left, request.validate !== false);
+  assertSamples('meteringCrestFactorDbStereo', request.right, request.validate !== false);
+  return requireModule().meteringCrestFactorDbStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+  );
+}
+
 export function meteringDcOffset(request: MeteringSamplesRequest): number;
 export function meteringDcOffset(
   samples: Float32Array,

package/src/project.ts

@@ -40,6 +40,9 @@ export type {
   ProjectMidiCcBindingKind,
   ProjectMidiClipResult,
   ProjectMidiEvent,
+  ProjectMidiFxBakeRequest,
+  ProjectMidiFxBakeResult,
+  ProjectMidiFxPreviewRequest,
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,

package/src/project_class.ts

@@ -35,6 +35,9 @@ import type {
   ProjectMidiCcBinding,
   ProjectMidiClipResult,
   ProjectMidiEvent,
+  ProjectMidiFxBakeRequest,
+  ProjectMidiFxBakeResult,
+  ProjectMidiFxPreviewRequest,
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
@@ -52,6 +55,28 @@ import type {
   SynthPatch,
 } from './project_types';
 
+/**
+ * Folds the positional and request call forms of `bakeMidiFx` into one shape,
+ * so defaults, validation and errors cannot diverge between them.
+ */
+function normalizeMidiFxBakeRequest(
+  clipIdOrRequest: number | ProjectMidiFxBakeRequest,
+  configJson?: string,
+): Required<ProjectMidiFxBakeRequest> {
+  if (typeof clipIdOrRequest === 'number') {
+    return {
+      clipId: clipIdOrRequest,
+      configJson: configJson ?? '',
+      withSourceIndex: false,
+    };
+  }
+  return {
+    clipId: clipIdOrRequest.clipId,
+    configJson: clipIdOrRequest.configJson,
+    withSourceIndex: clipIdOrRequest.withSourceIndex ?? false,
+  };
+}
+
 function validateAssistSidecarUint32(value: unknown, field: string): number {
   if (
     typeof value !== 'number' ||
@@ -584,8 +609,33 @@ export class Project {
    * Destructively bake a MIDI-FX chain into all stored events. Large clips are
    * drained without truncation; failure leaves the original clip unchanged.
    */
-  bakeMidiFx(clipId: number, configJson: string): void {
-    this.native.bakeMidiFx(clipId, configJson);
+  bakeMidiFx(clipId: number, configJson: string): void;
+  /**
+   * Request form. Setting `withSourceIndex` also returns per-event provenance,
+   * so a selection or an editorial annotation can be carried across the bake.
+   */
+  bakeMidiFx(request: ProjectMidiFxBakeRequest): ProjectMidiFxBakeResult;
+  bakeMidiFx(
+    clipIdOrRequest: number | ProjectMidiFxBakeRequest,
+    configJson?: string,
+  ): ProjectMidiFxBakeResult {
+    const request = normalizeMidiFxBakeRequest(clipIdOrRequest, configJson);
+    if (!request.withSourceIndex) {
+      this.native.bakeMidiFx(request.clipId, request.configJson);
+      return {};
+    }
+    return {
+      sourceIndex: this.native.bakeMidiFxWithSourceIndex(request.clipId, request.configJson),
+    };
+  }
+
+  /**
+   * Count the events {@link bakeMidiFx} would produce for this clip and
+   * configuration, without mutating the project. The transform is
+   * deterministic, so the count matches what the bake goes on to produce.
+   */
+  previewMidiFxCount(request: ProjectMidiFxPreviewRequest): number {
+    return this.native.previewMidiFxCount(request.clipId, request.configJson);
   }
 
   /** Backward alias for {@link bakeMidiFx}. */

package/src/project_internal.ts

@@ -85,6 +85,8 @@ export interface WasmProject {
     bank: number,
   ) => void;
   bakeMidiFx: (clipId: number, configJson: string) => void;
+  bakeMidiFxWithSourceIndex: (clipId: number, configJson: string) => Int32Array;
+  previewMidiFxCount: (clipId: number, configJson: string) => number;
   setMidiFx: (clipId: number, configJson: string) => void;
   validateMidiNotes: (clipId: number) => ProjectNotePairValidation;
   analyzeTempo: (audio: Float32Array, sampleRate: number) => ProjectTempoCandidate[];

package/src/project_types.ts

@@ -300,12 +300,11 @@ export interface SynthModRouting {
  *
  * The patch starts from a BASE — the named `preset` (see
  * {@link synthPresetNames}; a `"va:"` routing prefix is accepted) or, when
- * `preset` is omitted, the default subtractive patch. Every numeric field then
- * uses "0 / omit => keep the base value" (non-zero values override, clamped to
- * their audible ranges) and the enum fields reserve `'default'` as keep. The
- * frozen C ABI has no per-field presence bits, so explicit zero numeric
- * overrides (for example `ampSustain: 0`) cannot be represented; they keep the
- * base value. A non-empty `modRoutings` REPLACES the base mod matrix.
+ * `preset` is omitted, the default subtractive patch. Omitting a numeric field
+ * keeps the base value; supplying one overrides it (clamped to its audible
+ * range), including an explicit `0` such as `stereoSpread: 0`. The enum fields
+ * reserve `'default'` as keep. A `modRoutings` array REPLACES the base mod
+ * matrix, and an empty array clears it, while omitting the key keeps it.
  *
  * Mode-specific deep parameters (FM operator stacks, modal mode tables,
  * drawbar registrations, kit pieces, piano strings) travel inside the named
@@ -341,12 +340,10 @@ export interface SynthPatch {
   velToCutoffCents?: number;
   ampAttackMs?: number;
   ampDecayMs?: number;
-  /** 0 / omit keeps the base value; explicit zero sustain is not representable. */
   ampSustain?: number;
   ampReleaseMs?: number;
   filterAttackMs?: number;
   filterDecayMs?: number;
-  /** 0 / omit keeps the base value; explicit zero sustain is not representable. */
   filterSustain?: number;
   filterReleaseMs?: number;
   lfoRateHz?: number;
@@ -668,6 +665,40 @@ export interface ProjectNotePairValidation {
   unmatchedNoteOffs: number;
 }
 
+/**
+ * Request form of {@link Project.bakeMidiFx}. The positional
+ * `(clipId, configJson)` call stays supported and normalizes to this shape.
+ */
+export interface ProjectMidiFxBakeRequest {
+  /** Target MIDI clip id. */
+  clipId: number;
+  /** MIDI-FX chain configuration as JSON. */
+  configJson: string;
+  /** Return per-event provenance in the result. Default false. */
+  withSourceIndex?: boolean;
+}
+
+/** Result of the request form of {@link Project.bakeMidiFx}. */
+export interface ProjectMidiFxBakeResult {
+  /**
+   * One entry per transformed event in canonical order: the index of the input
+   * event it derives from, or -1 for an event with no originating input. Chord
+   * and arpeggiator fan-out makes several outputs share one source index, so a
+   * caller that treats the first output per index as the same event and the
+   * rest as newly generated can carry a selection across the bake. Present only
+   * when the request set `withSourceIndex`.
+   */
+  sourceIndex?: Int32Array;
+}
+
+/** Request form of {@link Project.previewMidiFxCount}. */
+export interface ProjectMidiFxPreviewRequest {
+  /** Target MIDI clip id. */
+  clipId: number;
+  /** MIDI-FX chain configuration as JSON. */
+  configJson: string;
+}
+
 /** One compile diagnostic (mirrors SonareProjectDiagnostic). */
 export interface ProjectDiagnostic {
   code: number;

package/src/public_types_mastering.ts

@@ -352,6 +352,15 @@ export interface MasteringChainConfig {
     releaseMs?: number;
     applyGainAtInputRate?: boolean;
   };
+  /**
+   * Dot-notation spelling of any leaf above, e.g. `'loudness.targetLufs': -20`
+   * beside or instead of `loudness: { targetLufs: -20 }`. It is the form the C
+   * ABI carries parameters in, so a caller assembling overrides dynamically can
+   * emit it directly; the core validates the key and rejects an unknown one.
+   * The nested spelling is canonical — prefer it in hand-written code, where it
+   * is checked field by field while a dotted key is only checked at run time.
+   */
+  [flatKey: `${string}.${string}`]: number | boolean | undefined;
 }
 
 /**

package/src/public_types_spectral.ts

@@ -1,5 +1,19 @@
 import type { ValidateOptions } from './validation';
 
+/**
+ * Per-frame voicing decision, one entry per `f0Hz` frame. A truthy or non-zero
+ * entry marks the frame voiced. The union covers what the analysis side hands
+ * back — `PitchResult.voicedFlag` is a `boolean[]` — as well as the typed and
+ * plain numeric arrays a caller may build directly, so a pitch track can be fed
+ * straight into pitch correction without a conversion step.
+ */
+export type VoicedFlags =
+  | Int32Array
+  | Uint8Array
+  | Float32Array
+  | readonly number[]
+  | readonly boolean[];
+
 /** Options for `pitchCorrectTimevarying`. All fields are optional. */
 export interface PitchCorrectOptions extends ValidateOptions {
   /** `'midi'` retunes toward `targetMidi`; `'scale'` snaps to the key. Default `'midi'`. */
@@ -20,8 +34,8 @@ export interface PitchCorrectOptions extends ValidateOptions {
   retuneSpeedMs?: number;
   /** Corrections below this are bypassed to preserve vibrato (cents). Default 20. */
   vibratoThresholdCents?: number;
-  /** Per-frame voiced flags (non-zero = voiced); omit to treat all frames as voiced. */
-  voiced?: Int32Array;
+  /** Per-frame voiced flags (truthy = voiced); omit to treat all frames as voiced. */
+  voiced?: VoicedFlags;
   /** Per-frame voicing probability in `[0, 1]`; omit to derive from `voiced`. */
   voicedProb?: Float32Array;
 }

package/src/realtime_engine.ts

@@ -823,6 +823,15 @@ export class RealtimeEngine {
    * Returns `-1` when the track, insert, or name is unknown. (The Python binding
    * raises a `SonareError` for an unknown id where Node/WASM return the `-1`
    * sentinel.)
+   *
+   * This trio is how a mastering processor gets time-varying automation: the
+   * `eq.*`, `dynamics.*`, `saturation.*`, `spectral.*`, `stereo.*`,
+   * `maximizer.*` and `multiband.*` processors are all available as strip
+   * inserts, so placing one on a strip and resolving its parameter here drives
+   * it at audio-block precision, live and offline alike. The whole-signal
+   * stages of the offline mastering chain (`repair.*`, `loudness`, and the
+   * match stages) have no insert form and no automation id: they buffer the
+   * entire signal by construction and do not run on the realtime path.
    */
   resolveTrackInsertAutomationId(trackId: number, insertIndex: number, paramName: string): number {
     return this.native.resolveTrackInsertAutomationId(trackId, insertIndex, paramName);
@@ -984,6 +993,36 @@ export class RealtimeEngine {
     this.native.processPrepared(numFrames);
   }
 
+  /**
+   * Allocates the cue-bus counterpart of {@link prepareChannels}. Needed only
+   * when PFL/AFL monitoring must reach a separate output: `processPrepared`
+   * folds the cue bus into the program output, while
+   * {@link processPreparedWithMonitor} keeps the two apart. Call once, off the
+   * audio thread, with at least as many channels as `prepareChannels` got.
+   */
+  prepareMonitorChannels(numChannels: number, maxFrames: number): void {
+    this.native.prepareMonitorChannels(numChannels, maxFrames);
+  }
+
+  /**
+   * Returns a Float32Array view onto the persistent cue-bus scratch for one
+   * channel (valid for up to `numFrames`). Read it after
+   * {@link processPreparedWithMonitor}. Re-acquire after WASM memory growth.
+   */
+  getMonitorChannelBuffer(channel: number, numFrames: number): Float32Array {
+    return this.native.getMonitorChannelBuffer(channel, numFrames);
+  }
+
+  /**
+   * Runs the engine in place over the prepared scratch, writing the cue bus to
+   * the monitor scratch instead of folding it into the program output.
+   * Allocation-free: safe on the AudioWorklet render thread after
+   * `prepareChannels` and `prepareMonitorChannels`.
+   */
+  processPreparedWithMonitor(numFrames: number): void {
+    this.native.processPreparedWithMonitor(numFrames);
+  }
+
   processWithMonitor(channels: Float32Array[]): WasmEngineProcessWithMonitorResult {
     return this.native.processWithMonitor(channels);
   }

package/src/sonare.js.d.ts

@@ -1114,6 +1114,9 @@ export interface WasmRealtimeEngine {
   prepareChannels: (numChannels: number, maxFrames: number) => void;
   getChannelBuffer: (channel: number, numFrames: number) => Float32Array;
   processPrepared: (numFrames: number) => void;
+  prepareMonitorChannels: (numChannels: number, maxFrames: number) => void;
+  getMonitorChannelBuffer: (channel: number, numFrames: number) => Float32Array;
+  processPreparedWithMonitor: (numFrames: number) => void;
   processWithMonitor: (channels: Float32Array[]) => WasmEngineProcessWithMonitorResult;
   renderOffline: (channels: Float32Array[], blockSize: number) => Float32Array[];
   bounceOffline: (options: WasmEngineBounceOptions) => WasmEngineBounceResult;
@@ -1328,6 +1331,11 @@ export interface SonareModule {
     hopLength: number,
   ) => number;
   meteringCrestFactorDb: (samples: Float32Array, sampleRate: number) => number;
+  meteringCrestFactorDbStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+  ) => number;
   meteringDcOffset: (samples: Float32Array, sampleRate: number) => number;
   meteringTruePeakDb: (
     samples: Float32Array,
@@ -1693,6 +1701,24 @@ export interface SonareModule {
     sampleRate: number,
     platforms: Array<{ name: string; targetLufs: number; ceilingDb: number }>,
   ) => string;
+  masteringAssistantSuggestStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => string;
+  masteringAudioProfileStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => string;
+  masteringStreamingPreviewStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    platforms: Array<{ name: string; targetLufs: number; ceilingDb: number }>,
+  ) => string;
   masteringRepairDeclick: (
     samples: Float32Array,
     sampleRate: number,

package/src/streaming_processors.ts

@@ -49,6 +49,24 @@ const EQ_PHASE_MODES: Record<string, number> = {
  * Call {@link delete} (or use a `try/finally`) to release the underlying WASM
  * object — the embind handle is not garbage-collected automatically.
  *
+ * Reachable from the AudioWorklet realm through the `sonare/worklet` entry, but
+ * the realtime contract is the caller's to keep:
+ *
+ * - {@link prepare} builds the processors and allocates. Call it once from a
+ *   message handler, never from `AudioWorkletProcessor.process()`.
+ * - {@link processMono}/{@link processStereo} return fresh arrays. On the render
+ *   thread, reuse the returned reference for the block rather than retaining it.
+ * - An enabled `loudness` stage needs `loudnessStaticGainDb` measured offline,
+ *   because whole-signal integrated LUFS cannot be measured block by block. Pass
+ *   `loudnessStaticGainPeakDb` too and the static gain is clamped exactly as the
+ *   offline chain clamps it, so the live preview matches the render.
+ * - {@link flush} output starts {@link latencySamples} samples early; discard
+ *   that many leading samples when time alignment matters.
+ *
+ * The chain is a host-side stage, not an engine insert: it does not participate
+ * in the engine's PDC or bypass, so latency compensation against other engine
+ * outputs is also the caller's.
+ *
  * @example
  * ```typescript
  * const chain = new StreamingMasteringChain({ eq: { tiltDb: 1.0 } });