@libraz/libsonare 1.5.2 → 1.5.4

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

@@ -1,5 +1,77 @@
 import { getSonareModule } from './module_state';
-import type { RealtimeVoiceChangerConfigInput, VoicePresetId } from './public_types';
+import type {
+  RealtimeVoiceChangerConfigInput,
+  RealtimeVoiceChangerPodConfig,
+  VoicePresetId,
+} from './public_types';
+
+/**
+ * True when `config` is a flat POD (the shape `realtimeVoiceChangerPresetConfig`
+ * returns) rather than a preset name or a nested preset. `retuneSemitones` only
+ * exists on the flat POD; the nested form spells it `retune.semitones`.
+ */
+function isFlatVoiceChangerPod(config: unknown): config is RealtimeVoiceChangerPodConfig {
+  return typeof config === 'object' && config !== null && 'retuneSemitones' in config;
+}
+
+/**
+ * Rewrite the flat 36-field POD into the nested shape the native config parser
+ * reads. Passing the flat POD straight to `setConfig` would leave every nested
+ * field at its default (only the three root fields are read flat), silently
+ * discarding retune/EQ/reverb/etc.
+ */
+function flatVoiceChangerPodToNested(pod: RealtimeVoiceChangerPodConfig): Record<string, unknown> {
+  return {
+    inputGainDb: pod.inputGainDb,
+    outputGainDb: pod.outputGainDb,
+    wetMix: pod.wetMix,
+    retune: { semitones: pod.retuneSemitones, mix: pod.retuneMix, grainSize: pod.retuneGrainSize },
+    formant: {
+      factor: pod.formantFactor,
+      amount: pod.formantAmount,
+      body: pod.formantBody,
+      brightness: pod.formantBrightness,
+      nasal: pod.formantNasal,
+    },
+    eq: {
+      highpassHz: pod.eqHighpassHz,
+      bodyDb: pod.eqBodyDb,
+      presenceDb: pod.eqPresenceDb,
+      airDb: pod.eqAirDb,
+    },
+    gate: {
+      thresholdDb: pod.gateThresholdDb,
+      attackMs: pod.gateAttackMs,
+      releaseMs: pod.gateReleaseMs,
+      rangeDb: pod.gateRangeDb,
+    },
+    compressor: {
+      thresholdDb: pod.compressorThresholdDb,
+      ratio: pod.compressorRatio,
+      attackMs: pod.compressorAttackMs,
+      releaseMs: pod.compressorReleaseMs,
+      makeupGainDb: pod.compressorMakeupGainDb,
+    },
+    deesser: {
+      frequencyHz: pod.deesserFrequencyHz,
+      thresholdDb: pod.deesserThresholdDb,
+      ratio: pod.deesserRatio,
+      rangeDb: pod.deesserRangeDb,
+    },
+    reverb: {
+      mix: pod.reverbMix,
+      timeMs: pod.reverbTimeMs,
+      damping: pod.reverbDamping,
+      seed: pod.reverbSeed,
+    },
+    limiter: {
+      ceilingDb: pod.limiterCeilingDb,
+      releaseMs: pod.limiterReleaseMs,
+      enableIspLimiter: pod.limiterEnableIspLimiter,
+      ispCeilingDbtp: pod.limiterIspCeilingDbtp,
+    },
+  };
+}
 
 /**
  * Zero-copy realtime buffer pair for {@link RealtimeVoiceChanger} mono
@@ -58,8 +130,12 @@ export class RealtimeVoiceChanger {
     this.changer.reset();
   }
 
-  setConfig(config: RealtimeVoiceChangerConfigInput): void {
-    this.changer.setConfig(config as Record<string, unknown> | string);
+  setConfig(config: RealtimeVoiceChangerConfigInput | RealtimeVoiceChangerPodConfig): void {
+    // A flat POD (from realtimeVoiceChangerPresetConfig) is rewritten to the
+    // nested shape the native parser reads; a preset name or nested preset is
+    // passed through unchanged.
+    const resolved = isFlatVoiceChangerPod(config) ? flatVoiceChangerPodToNested(config) : config;
+    this.changer.setConfig(resolved as Record<string, unknown> | string);
   }
 
   configJson(): string {

package/src/sonare.js.d.ts

@@ -470,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 {
@@ -482,6 +490,9 @@ export interface WasmMasteringStereoChainResult {
   outputLufs: number;
   appliedGainDb: number;
   stages: string[];
+  outputTruePeakDbtp: number;
+  outputLra: number;
+  stageGainReductions: WasmStageGainReduction[];
 }
 
 export interface WasmMasteringStereoResult {
@@ -734,6 +745,10 @@ export interface WasmEngineTransportState {
   barCount: number;
   /** Time signature in effect at the current PPQ. */
   timeSignature: { numerator: number; denominator: number; confidence: number };
+  /** One-based beat within the current bar (`barCount` is zero-based). */
+  beat: number;
+  /** Fractional position within the current beat, in [0, 1). */
+  beatFraction: number;
 }
 
 export interface WasmEngineBounceOptions {
@@ -848,6 +863,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;
@@ -1412,12 +1428,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,
@@ -2336,6 +2365,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;
@@ -2351,6 +2382,8 @@ export interface WasmFrameBuffer {
 export interface WasmStreamFramesU8 {
   nFrames: number;
   nMels: number;
+  nChroma: number;
+  featureFlags: number;
   timestamps: Float32Array;
   mel: Uint8Array;
   chroma: Uint8Array;
@@ -2363,6 +2396,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(
@@ -101,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();

package/src/stream_types.ts

@@ -78,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.
@@ -117,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;
@@ -130,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;
@@ -163,13 +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