@libraz/libsonare 1.5.1 → 1.5.3

package/src/realtime_engine.ts

@@ -587,6 +587,14 @@ export class RealtimeEngine {
     );
   }
 
+  /**
+   * Returns the PCM generated for a tempo-sync clip by the control-thread
+   * setter, or `null` when the clip did not require a tempo-sync bake.
+   */
+  prebakedClipChannels(clipId: number): Float32Array[] | null {
+    return this.native.prebakedClipChannels(clipId);
+  }
+
   clipCount(): number {
     return this.native.clipCount();
   }

package/src/sonare.js.d.ts

@@ -195,6 +195,7 @@ export interface WasmStreamConfigDefaults {
   emitEveryNFrames: number;
   magnitudeDownsample: number;
   maxPendingFrames: number;
+  maxProgressionEntries: number;
   keyUpdateIntervalSec: number;
   bpmUpdateIntervalSec: number;
   window: number;
@@ -469,8 +470,16 @@ export interface WasmMasteringResult {
   latencySamples?: number;
 }
 
+export interface WasmStageGainReduction {
+  stage: string;
+  gainReductionDb: number;
+}
+
 export interface WasmMasteringChainResult extends WasmMasteringResult {
   stages: string[];
+  outputTruePeakDbtp: number;
+  outputLra: number;
+  stageGainReductions: WasmStageGainReduction[];
 }
 
 export interface WasmMasteringStereoChainResult {
@@ -481,6 +490,9 @@ export interface WasmMasteringStereoChainResult {
   outputLufs: number;
   appliedGainDb: number;
   stages: string[];
+  outputTruePeakDbtp: number;
+  outputLra: number;
+  stageGainReductions: WasmStageGainReduction[];
 }
 
 export interface WasmMasteringStereoResult {
@@ -847,6 +859,7 @@ export interface WasmRealtimeEngine {
   graphNodeCount: () => number;
   graphConnectionCount: () => number;
   setClips: (clips: WasmEngineClip[]) => void;
+  prebakedClipChannels: (clipId: number) => Float32Array[] | null;
   clipCount: () => number;
   setTrackLanes: (lanes: Array<number | WasmEngineTrackLane>) => void;
   setLaneSidechain: (trackId: number, insertIndex: number, sourceTrackId: number) => void;
@@ -1411,12 +1424,25 @@ export interface SonareModule {
     offsetSample: number,
     stretchRatio: number,
   ) => Float32Array;
+  noteMove: (
+    samples: Float32Array,
+    sampleRate: number,
+    onsetSample: number,
+    offsetSample: number,
+    targetOnsetSample: number,
+  ) => Float32Array;
   voiceChange: (
     samples: Float32Array,
     sampleRate: number,
     pitchSemitones: number,
     formantFactor: number,
   ) => Float32Array;
+  voiceChangeRealtime: (
+    samples: Float32Array,
+    sampleRate: number,
+    preset: string,
+    channels: number,
+  ) => Float32Array;
   normalize: (samples: Float32Array, sampleRate: number, targetDb: number) => Float32Array;
   mastering: (
     samples: Float32Array,
@@ -1906,6 +1932,27 @@ export interface SonareModule {
     binsPerOctave: number,
     gamma: number,
   ) => WasmCqtResult;
+  cqtToAudio: (
+    magnitude: Float32Array,
+    nBins: number,
+    nFrames: number,
+    sampleRate: number,
+    hopLength: number,
+    fmin: number,
+    binsPerOctave: number,
+    nIter: number,
+  ) => Float32Array;
+  vqtToAudio: (
+    magnitude: Float32Array,
+    nBins: number,
+    nFrames: number,
+    sampleRate: number,
+    hopLength: number,
+    fmin: number,
+    binsPerOctave: number,
+    gamma: number,
+    nIter: number,
+  ) => Float32Array;
   analyzeSections: (
     samples: Float32Array,
     sampleRate: number,
@@ -2028,6 +2075,7 @@ export interface SonareModule {
     emitEveryNFrames: number,
     magnitudeDownsample: number,
     maxPendingFrames: number,
+    maxProgressionEntries: number,
     keyUpdateIntervalSec: number,
     bpmUpdateIntervalSec: number,
     window: number,
@@ -2304,6 +2352,8 @@ export interface WasmAnalyzerStats {
   durationSeconds: number;
   pendingFrames: number;
   droppedOutputFrames: number;
+  droppedChordProgressionEntries: number;
+  droppedBarProgressionEntries: number;
   estimate: WasmProgressiveEstimate;
 }
 
@@ -2311,6 +2361,8 @@ export interface WasmFrameBuffer {
   nFrames: number;
   /** Number of mel bands; flat `mel` is `[nFrames * nMels]` row-major. */
   nMels: number;
+  nChroma: number;
+  featureFlags: number;
   timestamps: Float32Array;
   mel: Float32Array;
   chroma: Float32Array;
@@ -2326,6 +2378,8 @@ export interface WasmFrameBuffer {
 export interface WasmStreamFramesU8 {
   nFrames: number;
   nMels: number;
+  nChroma: number;
+  featureFlags: number;
   timestamps: Float32Array;
   mel: Uint8Array;
   chroma: Uint8Array;
@@ -2338,6 +2392,8 @@ export interface WasmStreamFramesU8 {
 export interface WasmStreamFramesI16 {
   nFrames: number;
   nMels: number;
+  nChroma: number;
+  featureFlags: number;
   timestamps: Float32Array;
   mel: Int16Array;
   chroma: Int16Array;

package/src/stream_analyzer.ts

@@ -39,6 +39,16 @@ export function streamAnalyzerConfigDefaults(): StreamConfigDefaults {
  * console.log('Key:', stats.estimate.key);
  * console.log('Chord progression:', stats.estimate.chordProgression);
  * ```
+ *
+ * The native analyzer supports one serialized producer (`process`,
+ * `processWithOffset`, or `finalize`) concurrently with one serialized consumer
+ * (`availableFrames`, a `readFrames*` method, `stats`, `frameCount`, or
+ * `currentTime`) when a threaded WASM host shares the native instance.
+ * Publication is allocation-free release/acquire. `reset`, setters, and
+ * deletion require both roles to be stopped. A full pending ring drops the
+ * newly produced output frame while analysis totals keep advancing. Ordinary
+ * browser builds remain single-threaded unless the host explicitly provisions
+ * shared-memory worker support.
  */
 export class StreamAnalyzer {
   private analyzer: WasmStreamAnalyzer;
@@ -54,6 +64,15 @@ export class StreamAnalyzer {
         'computeMagnitude is not supported because magnitude frames are not exposed by StreamAnalyzer read paths.',
       );
     }
+    if (
+      config.outputFormat !== undefined &&
+      (typeof config.outputFormat !== 'number' ||
+        !Number.isFinite(config.outputFormat) ||
+        !Number.isInteger(config.outputFormat) ||
+        config.outputFormat !== 0)
+    ) {
+      throw new TypeError('outputFormat must be the integer 0 (Float32)');
+    }
     const module = getSonareModule();
     const defaults = streamAnalyzerConfigDefaults();
     this.analyzer = new module.StreamAnalyzer(
@@ -72,6 +91,7 @@ export class StreamAnalyzer {
       config.emitEveryNFrames ?? defaults.emitEveryNFrames,
       config.magnitudeDownsample ?? defaults.magnitudeDownsample,
       config.maxPendingFrames ?? defaults.maxPendingFrames,
+      config.maxProgressionEntries ?? defaults.maxProgressionEntries,
       config.keyUpdateIntervalSec ?? defaults.keyUpdateIntervalSec,
       config.bpmUpdateIntervalSec ?? defaults.bpmUpdateIntervalSec,
       config.window ?? defaults.window,
@@ -89,7 +109,8 @@ export class StreamAnalyzer {
   }
 
   /**
-   * Process audio samples with explicit sample offset.
+   * Process audio samples with a contiguous explicit sample offset. A gap,
+   * seek, or switch from `process()` requires `reset()` first.
    *
    * @param samples - Audio samples (mono, float32)
    * @param sampleOffset - Cumulative sample count at start of this chunk
@@ -99,7 +120,7 @@ export class StreamAnalyzer {
   }
 
   /**
-   * Flush the final partial frame with zero-padding.
+   * Drain any high-rate resampler tail, then zero-pad the final partial frame.
    */
   finalize(): void {
     this.analyzer.finalize();
@@ -166,6 +187,8 @@ export class StreamAnalyzer {
       durationSeconds: s.durationSeconds,
       pendingFrames: s.pendingFrames,
       droppedOutputFrames: s.droppedOutputFrames,
+      droppedChordProgressionEntries: s.droppedChordProgressionEntries,
+      droppedBarProgressionEntries: s.droppedBarProgressionEntries,
       estimate: {
         bpm: s.estimate.bpm,
         bpmConfidence: s.estimate.bpmConfidence,

package/src/stream_types.ts

@@ -66,6 +66,8 @@ export interface AnalyzerStats {
   durationSeconds: number;
   pendingFrames: number;
   droppedOutputFrames: number;
+  droppedChordProgressionEntries: number;
+  droppedBarProgressionEntries: number;
   estimate: ProgressiveEstimate;
 }
 
@@ -76,6 +78,10 @@ export interface FrameBuffer {
   nFrames: number;
   /** Number of mel bands; flat `mel` is `[nFrames * nMels]` row-major. */
   nMels: number;
+  /** Chroma stride: 12 when enabled, otherwise 0. */
+  nChroma: number;
+  /** MEL=1, CHROMA=2, ONSET=4, SPECTRAL=8. */
+  featureFlags: number;
   timestamps: Float32Array;
   /**
    * Mel spectrogram in LINEAR power (not dB) — the raw per-frame mel energies.
@@ -115,6 +121,9 @@ export interface StreamQuantizeConfig {
 export interface StreamFramesU8 {
   nFrames: number;
   nMels: number;
+  nChroma: number;
+  /** MEL=1, CHROMA=2, ONSET=4, SPECTRAL=8. */
+  featureFlags: number;
   timestamps: Float32Array;
   /** Row-major `[nFrames * nMels]` mel in dB, quantized over `[melDbMin, melDbMax]`. */
   mel: Uint8Array;
@@ -128,6 +137,9 @@ export interface StreamFramesU8 {
 export interface StreamFramesI16 {
   nFrames: number;
   nMels: number;
+  nChroma: number;
+  /** MEL=1, CHROMA=2, ONSET=4, SPECTRAL=8. */
+  featureFlags: number;
   timestamps: Float32Array;
   /** Row-major `[nFrames * nMels]` mel in dB, quantized over `[melDbMin, melDbMax]`. */
   mel: Int16Array;
@@ -161,11 +173,14 @@ export interface StreamConfig {
   computeSpectral?: boolean;
   emitEveryNFrames?: number;
   magnitudeDownsample?: number;
-  /** Maximum unread frames; overflow drops the oldest frame. */
+  /** Maximum unread frames; overflow drops the newly produced frame. */
   maxPendingFrames?: number;
+  /** Maximum retained chord and bar progression entries; overflow drops oldest. */
+  maxProgressionEntries?: number;
   keyUpdateIntervalSec?: number;
   bpmUpdateIntervalSec?: number;
   window?: number;
+  /** @deprecated Must be 0 (Float32). Use readFramesU8/readFramesI16 explicitly. */
   outputFormat?: number;
 }
 

package/src/validation.ts

@@ -14,6 +14,15 @@ export interface ValidateOptions {
   validate?: boolean;
 }
 
+/**
+ * Offline-analysis sample-rate bounds, mirroring the C++ core limits
+ * (`sonare::kMinAudioSampleRate` / `kMaxAudioSampleRate` in `core/audio.h`).
+ * Every guarded WASM entry point rejects the same out-of-range rates the C ABI,
+ * Node, and Python surfaces do.
+ */
+export const MIN_AUDIO_SAMPLE_RATE = 8000;
+export const MAX_AUDIO_SAMPLE_RATE = 384000;
+
 function assertNonEmptySamples(
   fnName: string,
   samples: ArrayLike<number>,
@@ -58,8 +67,14 @@ export function assertFiniteScalar(fnName: string, value: number, argName: strin
 }
 
 export function assertSampleRate(fnName: string, sampleRate: number): void {
-  if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 384000) {
-    throw new RangeError(`${fnName}: sampleRate out of supported range [8000, 384000]`);
+  if (
+    !Number.isInteger(sampleRate) ||
+    sampleRate < MIN_AUDIO_SAMPLE_RATE ||
+    sampleRate > MAX_AUDIO_SAMPLE_RATE
+  ) {
+    throw new RangeError(
+      `${fnName}: sampleRate out of supported range [${MIN_AUDIO_SAMPLE_RATE}, ${MAX_AUDIO_SAMPLE_RATE}]`,
+    );
   }
 }
 

package/src/worklet/engine-clips.ts

@@ -11,11 +11,17 @@ export interface EngineClipContext {
   readonly clips: Map<number, EngineClip>;
   readonly midiClips: Map<number, EngineMidiClipSchedule>;
   allocateClipId(): number;
-  postSync(message: SonareEngineSyncMessage): void;
+  postSync(message: SonareEngineSyncMessage, transfer?: Transferable[]): void;
   resolveTargetId(target: string | number): number;
   ensureTrackLane(target: string | number): number;
 }
 
+// Keep control-message work bounded even for long tempo-synced clips. The
+// worklet creates a native page provider, receives these transferable PCM
+// chunks, and only schedules the clip after all pages arrive.
+const PREBAKED_CLIP_PAGE_THRESHOLD = 16_384;
+const PREBAKED_CLIP_PAGE_FRAMES = 4_096;
+
 export function addClip(
   ctx: EngineClipContext,
   trackId: string | number,
@@ -57,9 +63,68 @@ export function setMidiClips(
 function syncClipsDelta(ctx: EngineClipContext, upserts: EngineClip[], removeIds: number[]): void {
   const clips = Array.from(ctx.clips.values());
   ctx.offlineEngine.setClips(clips);
+  const preparedById = new Map<number, EngineClip>();
+  for (const clip of clips) {
+    if (clip.id === undefined) {
+      continue;
+    }
+    const bakedChannels = ctx.offlineEngine.prebakedClipChannels(clip.id);
+    preparedById.set(
+      clip.id,
+      bakedChannels === null
+        ? clip
+        : {
+            ...clip,
+            channels: bakedChannels,
+            clipOffsetSamples: 0,
+            lengthSamples: bakedChannels[0]?.length ?? 0,
+            loop: false,
+            warpMode: 'off',
+            warpAnchors: undefined,
+          },
+    );
+  }
+  const inlineUpserts: EngineClip[] = [];
+  for (const clip of upserts) {
+    const prepared = clip.id === undefined ? clip : (preparedById.get(clip.id) ?? clip);
+    const channels = prepared.channels;
+    if (
+      prepared.id === undefined ||
+      prepared.warpMode !== 'off' ||
+      !channels ||
+      channels.length === 0 ||
+      channels[0].length <= PREBAKED_CLIP_PAGE_THRESHOLD
+    ) {
+      inlineUpserts.push(prepared);
+      continue;
+    }
+    const numSamples = channels[0].length;
+    ctx.postSync({
+      type: 'syncClipPageProvider',
+      clipId: prepared.id,
+      clip: { ...prepared, channels: undefined, pageProvider: undefined },
+      numChannels: channels.length,
+      numSamples,
+      pageFrames: PREBAKED_CLIP_PAGE_FRAMES,
+    });
+    for (
+      let start = 0, pageIndex = 0;
+      start < numSamples;
+      start += PREBAKED_CLIP_PAGE_FRAMES, pageIndex++
+    ) {
+      const page = channels.map((channel) =>
+        channel.slice(start, start + PREBAKED_CLIP_PAGE_FRAMES),
+      );
+      ctx.postSync(
+        { type: 'syncClipPage', clipId: prepared.id, pageIndex, channels: page },
+        page.map((channel) => channel.buffer as Transferable),
+      );
+    }
+    ctx.postSync({ type: 'syncClipPageCommit', clipId: prepared.id });
+  }
   ctx.postSync({
     type: 'syncClipsDelta',
-    upserts,
+    upserts: inlineUpserts,
     removeIds,
   });
 }

package/src/worklet/engine-processor.ts

@@ -70,6 +70,8 @@ export class SonareRealtimeEngineWorkletProcessor {
   // arrays on both heaps every block, an RT-safety hazard).
   private channelBuffers: Float32Array[];
   private readonly liveClips = new Map<number, EngineClip>();
+  private readonly pagedClipProviders = new Map<number, number>();
+  private readonly pendingPagedClips = new Map<number, EngineClip>();
 
   constructor(
     options: SonareRealtimeEngineWorkletProcessorOptions = {},
@@ -208,11 +210,10 @@ export class SonareRealtimeEngineWorkletProcessor {
     }
   }
 
-  // Applies an out-of-band control-plane sync message. Runs on the AudioWorklet
-  // global scope but OUTSIDE process() (the message-port callback), so the
-  // bulk/allocating engine setters (setClips/setMarkers) are safe here — they
-  // never run on the realtime render path. This is the audio-thread equivalent
-  // of the engine's control-thread RtPublisher setters.
+  // Applies an out-of-band control-plane sync message on the AudioWorklet
+  // thread. These handlers must remain bounded: expensive clip transforms are
+  // performed on the main-thread mirror, and long pre-baked PCM arrives in
+  // small pages before the final lightweight clip schedule is committed.
   receiveSync(message: SonareEngineSyncMessage): void {
     if (this.closed) {
       return;
@@ -238,6 +239,33 @@ export class SonareRealtimeEngineWorkletProcessor {
         }
         this.engine.setClips(Array.from(this.liveClips.values()));
         break;
+      case 'syncClipPageProvider': {
+        const provider = this.engine.createClipPageProvider(
+          message.numChannels,
+          message.numSamples,
+          message.pageFrames,
+        );
+        this.pagedClipProviders.set(message.clipId, provider.id);
+        this.pendingPagedClips.set(message.clipId, message.clip);
+        break;
+      }
+      case 'syncClipPage': {
+        const providerId = this.pagedClipProviders.get(message.clipId);
+        if (providerId !== undefined) {
+          this.engine.supplyClipPage(providerId, message.pageIndex, message.channels);
+        }
+        break;
+      }
+      case 'syncClipPageCommit': {
+        const providerId = this.pagedClipProviders.get(message.clipId);
+        const clip = this.pendingPagedClips.get(message.clipId);
+        if (providerId !== undefined && clip) {
+          this.liveClips.set(message.clipId, { ...clip, pageProvider: providerId });
+          this.pendingPagedClips.delete(message.clipId);
+          this.engine.setClips(Array.from(this.liveClips.values()));
+        }
+        break;
+      }
       case 'syncMidiClips':
         this.engine.setMidiClips(message.clips);
         break;

package/src/worklet/engine.ts

@@ -787,11 +787,15 @@ export class SonareEngine {
   // Posts an out-of-band control-sync message to the worklet engine processor.
   // Sync messages use a string `type` so the worklet's message handler routes
   // them to receiveSync() (numeric `type` is reserved for SonareEngineCommandRecord).
-  private postSync(message: SonareEngineSyncMessage): void {
+  private postSync(message: SonareEngineSyncMessage, transfer?: Transferable[]): void {
     if (this.destroyed) {
       return;
     }
-    this.realtimeNode.node.port.postMessage(message);
+    if (transfer && transfer.length > 0) {
+      this.realtimeNode.node.port.postMessage(message, transfer);
+    } else {
+      this.realtimeNode.node.port.postMessage(message);
+    }
   }
 
   // Collaborator surface handed to the mixer/routing free functions so they can
@@ -916,7 +920,7 @@ export class SonareEngine {
       clips: this.clips,
       midiClips: this.midiClips,
       allocateClipId: () => this.nextClipId++,
-      postSync: (message) => this.postSync(message),
+      postSync: (message, transfer) => this.postSync(message, transfer),
       ensureTrackLane: (target) => this.ensureTrackLane(target),
       resolveTargetId: (target) => this.resolveTargetId(target),
     };

package/src/worklet/guards.ts

@@ -37,6 +37,9 @@ export function isEngineSyncMessage(value: unknown): value is SonareEngineSyncMe
   return (
     value.type === 'syncClips' ||
     value.type === 'syncClipsDelta' ||
+    value.type === 'syncClipPageProvider' ||
+    value.type === 'syncClipPage' ||
+    value.type === 'syncClipPageCommit' ||
     value.type === 'syncMidiClips' ||
     value.type === 'syncMarkers' ||
     value.type === 'syncMetronome' ||

package/src/worklet/messages.ts

@@ -219,6 +219,30 @@ export interface SonareEngineSyncClipsDeltaMessage {
   removeIds: number[];
 }
 
+/** Begins a paged, pre-baked clip transfer. PCM pages follow in FIFO order. */
+export interface SonareEngineSyncClipPageProviderMessage {
+  type: 'syncClipPageProvider';
+  clipId: number;
+  clip: EngineClip;
+  numChannels: number;
+  numSamples: number;
+  pageFrames: number;
+}
+
+/** Supplies one bounded PCM page for a pending pre-baked clip transfer. */
+export interface SonareEngineSyncClipPageMessage {
+  type: 'syncClipPage';
+  clipId: number;
+  pageIndex: number;
+  channels: Float32Array[];
+}
+
+/** Makes a fully supplied paged clip visible to the audio engine. */
+export interface SonareEngineSyncClipPageCommitMessage {
+  type: 'syncClipPageCommit';
+  clipId: number;
+}
+
 export interface SonareEngineSyncMidiClipsMessage {
   type: 'syncMidiClips';
   clips: EngineMidiClipSchedule[];
@@ -433,6 +457,9 @@ export type SonareEngineInstrumentSyncMessage =
 export type SonareEngineSyncMessage =
   | SonareEngineSyncClipsMessage
   | SonareEngineSyncClipsDeltaMessage
+  | SonareEngineSyncClipPageProviderMessage
+  | SonareEngineSyncClipPageMessage
+  | SonareEngineSyncClipPageCommitMessage
   | SonareEngineSyncMidiClipsMessage
   | SonareEngineSyncMarkersMessage
   | SonareEngineSyncMetronomeMessage