@libraz/libsonare 1.7.1 → 1.7.2

package/package.json

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

package/src/index.ts

@@ -438,6 +438,9 @@ export type {
   ProjectMarker,
   ProjectMidiClipResult,
   ProjectMidiEvent,
+  ProjectMidiFxBakeRequest,
+  ProjectMidiFxBakeResult,
+  ProjectMidiFxPreviewRequest,
   ProjectNotePairValidation,
   ProjectSource,
   ProjectTrack,

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

@@ -665,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/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;

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

package/src/worklet/engine-node.ts

@@ -301,10 +301,12 @@ export class SonareRealtimeEngineNode {
         ? createSonareExternalMidiRingBuffer(options.externalMidiRingCapacity ?? 256)
         : undefined;
     const channelCount = Math.max(1, Math.floor(options.channelCount ?? 2));
+    const cueOutput = options.cueOutput === true;
     const processorOptions: SonareRealtimeEngineWorkletProcessorOptions = {
       sampleRate: options.sampleRate ?? context.sampleRate,
       blockSize,
       channelCount,
+      cueOutput,
       commandSharedBuffer: commandRing?.sharedBuffer,
       commandRingCapacity: commandRing?.capacity,
       telemetrySharedBuffer: telemetryRing?.sharedBuffer,
@@ -329,8 +331,10 @@ export class SonareRealtimeEngineNode {
         new AudioWorkletNode(ctx, name, nodeOptions));
     const node = factory(context, processorName, {
       numberOfInputs: 1,
-      numberOfOutputs: 1,
-      outputChannelCount: [channelCount],
+      // The cue bus needs its own output; a single-output node keeps the
+      // historical mix where process() folds the cue into the program.
+      numberOfOutputs: cueOutput ? 2 : 1,
+      outputChannelCount: cueOutput ? [channelCount, channelCount] : [channelCount],
       processorOptions,
     });
     return new SonareRealtimeEngineNode(
@@ -343,6 +347,7 @@ export class SonareRealtimeEngineNode {
         audioWorklet,
         clipPageRequestsRealtimeSafe: mode === 'sab',
         externalMidiRealtimeSafe: mode === 'sab',
+        cueOutput,
         engineAbiVersion: detectedCapabilities?.engineAbiVersion,
         expectedEngineAbiVersion: detectedCapabilities?.expectedEngineAbiVersion,
         abiCompatible: detectedCapabilities?.abiCompatible,

package/src/worklet/engine-processor.ts

@@ -46,6 +46,30 @@ import {
   writeSonareEngineTelemetryRingBuffer,
 } from './protocol';
 
+/**
+ * Copies one plane per output channel, zero-filling the tail past `frames` and
+ * any channel the source does not cover. Shared by the program and cue outputs
+ * so the two cannot drift in their padding behaviour. Allocation-free.
+ */
+function copyPlanesToOutput(
+  output: Float32Array[],
+  planes: readonly Float32Array[],
+  frames: number,
+): void {
+  for (let ch = 0; ch < output.length; ch++) {
+    const target = output[ch];
+    const source = planes[ch] ?? planes[0];
+    if (source) {
+      target.set(source.subarray(0, Math.min(target.length, frames)));
+      if (target.length > frames) {
+        target.fill(0, frames);
+      }
+    } else {
+      target.fill(0);
+    }
+  }
+}
+
 function captureTransferList(channels: readonly Float32Array[]): Transferable[] {
   const transfers: ArrayBuffer[] = [];
   const seen = new Set<ArrayBuffer>();
@@ -94,6 +118,11 @@ export class SonareRealtimeEngineWorkletProcessor {
   // allocated per render quantum (the old engine.process() round-tripped fresh
   // arrays on both heaps every block, an RT-safety hazard).
   private channelBuffers: Float32Array[];
+  // Cue-bus plane, allocated only when the host asked for a separate PFL/AFL
+  // output. Empty otherwise, so a single-output host pays no heap and keeps the
+  // historical behaviour where process() folds the cue into the program mix.
+  private monitorBuffers: Float32Array[] = [];
+  private readonly cueOutput: boolean;
   private readonly liveClips = new Map<number, EngineClip>();
   private readonly pagedClipProviders = new Map<number, number>();
   private readonly pagedClipPageFrames = new Map<number, number>();
@@ -160,6 +189,14 @@ export class SonareRealtimeEngineWorkletProcessor {
     for (let ch = 0; ch < this.channelCount; ch++) {
       this.channelBuffers[ch] = this.engine.getChannelBuffer(ch, this.blockSize);
     }
+    this.cueOutput = options.cueOutput === true;
+    if (this.cueOutput) {
+      this.engine.prepareMonitorChannels(this.channelCount, this.blockSize);
+      this.monitorBuffers = new Array(this.channelCount);
+      for (let ch = 0; ch < this.channelCount; ch++) {
+        this.monitorBuffers[ch] = this.engine.getMonitorChannelBuffer(ch, this.blockSize);
+      }
+    }
     // Arm the engine's scope producer only when a scope ring was provided. The
     // band count follows the ring's record layout so writeScopeRing never
     // overruns its slot.
@@ -213,6 +250,9 @@ export class SonareRealtimeEngineWorkletProcessor {
     if ((this.channelBuffers[0]?.byteLength ?? 0) === 0) {
       this.reacquireChannelBuffers();
     }
+    if (this.cueOutput && (this.monitorBuffers[0]?.byteLength ?? 0) === 0) {
+      this.reacquireMonitorBuffers();
+    }
 
     const input = inputs[0];
     // Write the AudioWorklet input straight into the engine's WASM-heap views;
@@ -227,19 +267,20 @@ export class SonareRealtimeEngineWorkletProcessor {
       }
     }
 
-    // Run the engine in place over the prepared scratch (allocation-free).
-    this.engine.processPrepared(usableFrames);
+    // Run the engine in place over the prepared scratch (allocation-free). The
+    // monitor variant keeps the cue bus out of the program planes so it can go
+    // to its own output; the plain call folds it in, as it always has.
+    if (this.cueOutput) {
+      this.engine.processPreparedWithMonitor(usableFrames);
+    } else {
+      this.engine.processPrepared(usableFrames);
+    }
 
-    for (let ch = 0; ch < output.length; ch++) {
-      const target = output[ch];
-      const source = this.channelBuffers[ch] ?? this.channelBuffers[0];
-      if (source) {
-        target.set(source.subarray(0, Math.min(target.length, usableFrames)));
-        if (target.length > usableFrames) {
-          target.fill(0, usableFrames);
-        }
-      } else {
-        target.fill(0);
+    copyPlanesToOutput(output, this.channelBuffers, usableFrames);
+    if (this.cueOutput) {
+      const cue = outputs[1];
+      if (cue) {
+        copyPlanesToOutput(cue, this.monitorBuffers, usableFrames);
       }
     }
     this.publishClipPageRequests();
@@ -256,6 +297,12 @@ export class SonareRealtimeEngineWorkletProcessor {
     }
   }
 
+  private reacquireMonitorBuffers(): void {
+    for (let ch = 0; ch < this.channelCount; ch++) {
+      this.monitorBuffers[ch] = this.engine.getMonitorChannelBuffer(ch, this.blockSize);
+    }
+  }
+
   receiveCommand(command: SonareEngineCommandRecord): void {
     if (!this.closed) {
       this.safeApplyCommand(command);

package/src/worklet/messages.ts

@@ -67,6 +67,13 @@ export interface SonareRealtimeEngineWorkletProcessorOptions {
   /** Lock-free worklet-to-main-thread MIDI-1 output ring. */
   externalMidiSharedBuffer?: SharedArrayBuffer;
   externalMidiRingCapacity?: number;
+  /**
+   * Route the PFL/AFL cue bus to the processor's SECOND output instead of
+   * folding it into the program output. Off by default, so an existing
+   * single-output host keeps its current mix sample for sample. The node must
+   * be constructed with two outputs for the cue to be audible.
+   */
+  cueOutput?: boolean;
 }
 
 export interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
@@ -105,6 +112,11 @@ export interface SonareRealtimeEngineNodeCapabilities {
   clipPageRequestsRealtimeSafe: boolean;
   /** True when external MIDI uses the SAB output ring rather than postMessage. */
   externalMidiRealtimeSafe: boolean;
+  /**
+   * True when the node carries a second output fed by the PFL/AFL cue bus. When
+   * false the cue is folded into the program output, as it always was.
+   */
+  cueOutput: boolean;
   engineAbiVersion?: number;
   expectedEngineAbiVersion?: number;
   abiCompatible?: boolean;

package/src/worklet.ts

@@ -10,6 +10,11 @@ export { attachOpfsClipStream } from './clip_page_streamer';
 // module singleton. Re-export the lifecycle so that realm can initialize its
 // own wasm instance, independent of the main-thread `index` module.
 export { init, isInitialized } from './index';
+// Host-side mastering preview inside the worklet realm. Kept here rather than
+// left main-thread-only so a live preview does not have to round-trip audio to
+// the main thread; see the class doc for the prepare/loudness/latency contract.
+export type { StreamingMasteringChainConfig } from './public_types';
+export { StreamingMasteringChain } from './streaming_processors';
 export { SonareEngine } from './worklet/engine';
 export { SonareRealtimeEngineNode } from './worklet/engine-node';
 export type { SonareEngineOptions } from './worklet/engine-options';