@libraz/libsonare 1.2.0 → 1.2.2

package/dist/worklet.js

@@ -29,6 +29,21 @@ function panLawCode(panLaw) {
       return 0;
   }
 }
+function panModeCode(panMode) {
+  if (typeof panMode === "number") {
+    return panMode;
+  }
+  switch (panMode) {
+    case "stereoPan":
+    case "stereo-pan":
+      return 1;
+    case "dualPan":
+    case "dual-pan":
+      return 2;
+    default:
+      return 0;
+  }
+}
 function meterTapCode(tap) {
   return tap === "preFader" || tap === 0 ? 0 : 1;
 }
@@ -236,6 +251,141 @@ var RealtimeEngine = class {
     this.native.delete();
   }
 };
+var RealtimeVoiceChanger = class {
+  constructor(config = "neutral-monitor") {
+    if (!module) {
+      throw new Error("Module not initialized. Call init() first.");
+    }
+    this.changer = module.createRealtimeVoiceChanger(config);
+  }
+  prepare(sampleRate, maxBlockSize = 128, channels = 1) {
+    this.changer.prepare(sampleRate, maxBlockSize, channels);
+  }
+  reset() {
+    this.changer.reset();
+  }
+  setConfig(config) {
+    this.changer.setConfig(config);
+  }
+  configJson() {
+    return this.changer.configJson();
+  }
+  latencySamples() {
+    return this.changer.latencySamples();
+  }
+  processMono(samples) {
+    return this.changer.processMono(samples);
+  }
+  processMonoInto(samples, output) {
+    this.changer.processMonoInto(samples, output);
+  }
+  processInterleaved(samples, channels) {
+    return this.changer.processInterleaved(samples, channels);
+  }
+  processInterleavedInto(samples, channels, output) {
+    this.changer.processInterleavedInto(samples, channels, output);
+  }
+  /**
+   * Acquire a typed-memory view onto the WASM heap for mono input.
+   *
+   * Write your input samples into the returned `Float32Array` directly (e.g.
+   * via `input.set(source)`); no copy crosses the JS↔C++ bridge until
+   * {@link processPreparedMono} is called. The view is owned by this
+   * RealtimeVoiceChanger and becomes invalid after {@link delete}; it may
+   * also be invalidated if you later call this method with a larger
+   * `numSamples` value (the underlying buffer may be reallocated).
+   */
+  getMonoInputBuffer(numSamples) {
+    return this.changer.getMonoInputBuffer(numSamples);
+  }
+  /** Mono output view counterpart to {@link getMonoInputBuffer}. */
+  getMonoOutputBuffer(numSamples) {
+    return this.changer.getMonoOutputBuffer(numSamples);
+  }
+  /**
+   * Process the previously-acquired mono input buffer in place. The output
+   * appears in the buffer returned by {@link getMonoOutputBuffer}. No JS↔C++
+   * sample-level crossings happen on this call — it just hands control to
+   * the underlying DSP on already-on-heap data.
+   */
+  processPreparedMono(numSamples) {
+    this.changer.processPreparedMono(numSamples);
+  }
+  /** Interleaved input view (layout L0,R0,L1,R1,...). */
+  getInterleavedInputBuffer(numFrames, numChannels) {
+    return this.changer.getInterleavedInputBuffer(numFrames, numChannels);
+  }
+  /** Interleaved output view counterpart. */
+  getInterleavedOutputBuffer(numFrames, numChannels) {
+    return this.changer.getInterleavedOutputBuffer(numFrames, numChannels);
+  }
+  /**
+   * Process the previously-acquired interleaved buffer in place. Output
+   * appears in the buffer returned by {@link getInterleavedOutputBuffer}.
+   */
+  processPreparedInterleaved(numFrames, numChannels) {
+    this.changer.processPreparedInterleaved(numFrames, numChannels);
+  }
+  /**
+   * Planar-channel input/output view (one Float32Array per channel). Matches
+   * AudioWorklet's native layout; processing happens in place.
+   */
+  getPlanarChannelBuffer(channel, numFrames) {
+    return this.changer.getPlanarChannelBuffer(channel, numFrames);
+  }
+  /**
+   * Process the previously-acquired planar channel buffers in place. Each
+   * channel must have been obtained from {@link getPlanarChannelBuffer}
+   * with the same `numFrames`. Output replaces input in the same buffers.
+   */
+  processPreparedPlanar(numFrames) {
+    this.changer.processPreparedPlanar(numFrames);
+  }
+  /**
+   * Convenience factory for the mono zero-copy path: returns the input/output
+   * heap views plus a `process()` thunk wired to the same `numSamples`. The
+   * views are reused across calls and become invalid after {@link delete}.
+   */
+  createRealtimeMonoBuffer(numSamples) {
+    const input = this.getMonoInputBuffer(numSamples);
+    const output = this.getMonoOutputBuffer(numSamples);
+    return {
+      input,
+      output,
+      process: () => this.processPreparedMono(numSamples)
+    };
+  }
+  /** Same as {@link createRealtimeMonoBuffer} but for interleaved I/O. */
+  createRealtimeInterleavedBuffer(numFrames, numChannels) {
+    const input = this.getInterleavedInputBuffer(numFrames, numChannels);
+    const output = this.getInterleavedOutputBuffer(numFrames, numChannels);
+    return {
+      input,
+      output,
+      channels: numChannels,
+      process: () => this.processPreparedInterleaved(numFrames, numChannels)
+    };
+  }
+  /**
+   * Convenience factory for the planar zero-copy path. Acquires one
+   * heap-backed Float32Array per channel and returns a `process()` thunk
+   * wired to the same `numFrames`. Buffers are reused across calls and
+   * become invalid after {@link delete}.
+   */
+  createRealtimePlanarBuffer(numFrames, numChannels) {
+    const channels = [];
+    for (let ch = 0; ch < numChannels; ch++) {
+      channels.push(this.getPlanarChannelBuffer(ch, numFrames));
+    }
+    return {
+      channels,
+      process: () => this.processPreparedPlanar(numFrames)
+    };
+  }
+  delete() {
+    this.changer.delete();
+  }
+};
 var Mixer = class _Mixer {
   constructor(mixer) {
     this.mixer = mixer;
@@ -379,6 +529,26 @@ var Mixer = class _Mixer {
   vcaGroupCount() {
     return this.mixer.vcaGroupCount();
   }
+  /** Set the strip's input trim in dB. */
+  setInputTrimDb(stripIndex, db) {
+    this.mixer.setInputTrimDb(stripIndex, db);
+  }
+  /** Set the strip's fader level in dB. */
+  setFaderDb(stripIndex, db) {
+    this.mixer.setFaderDb(stripIndex, db);
+  }
+  /** Set the strip's pan position. */
+  setPan(stripIndex, pan, panMode = 0) {
+    this.mixer.setPan(stripIndex, pan, panModeCode(panMode));
+  }
+  /** Set the strip's stereo width. */
+  setWidth(stripIndex, width) {
+    this.mixer.setWidth(stripIndex, width);
+  }
+  /** Set the strip's mute state. */
+  setMuted(stripIndex, muted) {
+    this.mixer.setMuted(stripIndex, muted);
+  }
   /**
    * Set a strip's solo state. Takes effect on the next process without a
    * graph recompile.
@@ -589,6 +759,12 @@ function isWorkletMessage(value) {
 function isEngineCommandRecord(value) {
   return isRecord(value) && typeof value.type === "number";
 }
+function isRealtimeVoiceChangerMessage(value) {
+  if (!isRecord(value) || typeof value.type !== "string") {
+    return false;
+  }
+  return value.type === "setConfig" || value.type === "reset" || value.type === "destroy";
+}
 function isEngineTelemetryRecord(value) {
   return isRecord(value) && typeof value.type === "number" && typeof value.error === "number" && typeof value.renderFrame === "number" && typeof value.timelineSample === "number" && typeof value.audibleTimelineSample === "number" && typeof value.graphLatencySamplesQ8 === "number" && typeof value.value === "number";
 }
@@ -1111,7 +1287,7 @@ var SonareWorkletProcessor = class {
     }
   }
 };
-var SonareRealtimeEngineWorkletProcessor = class {
+var _SonareRealtimeEngineWorkletProcessor = class _SonareRealtimeEngineWorkletProcessor {
   constructor(options = {}, transport) {
     this.closed = false;
     this.lastMeterFrame = Number.NEGATIVE_INFINITY;
@@ -1132,6 +1308,12 @@ var SonareRealtimeEngineWorkletProcessor = class {
       options.telemetryRingCapacity
     ) : void 0;
     this.engine = new RealtimeEngine(this.sampleRate, this.blockSize);
+    this.channelScratch = new Array(this.channelCount);
+    this.channelScratchViews = new Array(this.channelCount);
+    for (let ch = 0; ch < this.channelCount; ch++) {
+      this.channelScratch[ch] = new Float32Array(this.blockSize);
+      this.channelScratchViews[ch] = this.channelScratch[ch];
+    }
   }
   process(inputs, outputs) {
     if (this.closed) {
@@ -1151,17 +1333,29 @@ var SonareRealtimeEngineWorkletProcessor = class {
       return true;
     }
     this.drainCommands();
-    const channels = [];
+    const scratchCapacity = this.channelScratch[0]?.length ?? 0;
+    let usableFrames = frames;
+    if (usableFrames > scratchCapacity) {
+      if (!_SonareRealtimeEngineWorkletProcessor.warnedChannelScratchOverflow) {
+        _SonareRealtimeEngineWorkletProcessor.warnedChannelScratchOverflow = true;
+        console.warn(
+          `SonareRealtimeEngineWorkletProcessor: requested ${usableFrames} frames exceeds pre-allocated capacity ${scratchCapacity}; clamping.`
+        );
+      }
+      usableFrames = scratchCapacity;
+    }
     const input = inputs[0];
     for (let ch = 0; ch < this.channelCount; ch++) {
+      const scratch = this.channelScratch[ch];
       const source = input?.[ch];
-      const channel = new Float32Array(frames);
-      if (source && source.length === frames) {
-        channel.set(source);
+      if (source && source.length === usableFrames) {
+        scratch.set(source, 0);
+      } else {
+        scratch.fill(0, 0, usableFrames);
       }
-      channels.push(channel);
+      this.channelScratchViews[ch] = scratch.subarray(0, usableFrames);
     }
-    const processed = this.engine.process(channels);
+    const processed = this.engine.process(this.channelScratchViews);
     for (let ch = 0; ch < output.length; ch++) {
       const target = output[ch];
       const source = processed[ch] ?? processed[0];
@@ -1297,6 +1491,8 @@ var SonareRealtimeEngineWorkletProcessor = class {
     return { sharedBuffer, header: ring.header, view: ring.view, capacity: ring.capacity };
   }
 };
+_SonareRealtimeEngineWorkletProcessor.warnedChannelScratchOverflow = false;
+var SonareRealtimeEngineWorkletProcessor = _SonareRealtimeEngineWorkletProcessor;
 var SonareRtRealtimeEngineRuntime = class {
   constructor(options) {
     this.closed = false;
@@ -1931,6 +2127,140 @@ var SonareEngine = class _SonareEngine {
     return Math.max(0, Math.round(ppq * 60 / 120 * this.sampleRate));
   }
 };
+var _SonareRealtimeVoiceChangerWorkletProcessor = class _SonareRealtimeVoiceChangerWorkletProcessor {
+  constructor(options = {}) {
+    this.destroyed = false;
+    this.sampleRate = options.sampleRate ?? 48e3;
+    this.blockSize = options.blockSize ?? 128;
+    this.channelCount = Math.max(1, Math.floor(options.channelCount ?? 1));
+    this.changer = new RealtimeVoiceChanger(options.preset ?? "neutral-monitor");
+    this.changer.prepare(this.sampleRate, this.blockSize, this.channelCount);
+    this.monoInput = this.changer.getMonoInputBuffer(this.blockSize);
+    this.monoOutput = this.changer.getMonoOutputBuffer(this.blockSize);
+    this.planarChannels = [];
+    if (this.channelCount > 1) {
+      for (let ch = 0; ch < this.channelCount; ch++) {
+        this.planarChannels.push(this.changer.getPlanarChannelBuffer(ch, this.blockSize));
+      }
+    }
+  }
+  /**
+   * Handles a control-plane message from the main thread. Runs on the
+   * AudioWorklet global scope but OUTSIDE of `process()` (i.e. outside the
+   * realtime audio callback), so it is safe to perform JSON parsing and
+   * DSP coefficient recomputation here. `setConfig` MUST NOT be deferred
+   * into `process()` because that would block the audio thread for longer
+   * than one render quantum (e.g. 128 samples / 44.1 kHz = ~2.9 ms).
+   */
+  receiveMessage(message) {
+    if (this.destroyed) {
+      return;
+    }
+    if (message.type === "setConfig") {
+      this.changer.setConfig(message.preset);
+    } else if (message.type === "reset") {
+      this.changer.reset();
+    } else if (message.type === "destroy") {
+      this.destroy();
+    }
+  }
+  process(inputs, outputs) {
+    const output = outputs[0];
+    if (this.destroyed || !output || output.length === 0) {
+      return !this.destroyed;
+    }
+    const input = inputs[0];
+    const requestedFrames = output[0]?.length ?? 0;
+    const requestedChannels = Math.min(this.channelCount, output.length);
+    if (requestedFrames === 0 || requestedChannels === 0) {
+      return true;
+    }
+    if (requestedChannels === 1) {
+      const frames2 = this.ensureMonoCapacity(requestedFrames);
+      const source = input?.[0];
+      if (source) {
+        this.monoInput.set(source.subarray(0, frames2));
+      } else {
+        this.monoInput.fill(0, 0, frames2);
+      }
+      this.changer.processMonoInto(
+        this.monoInput.subarray(0, frames2),
+        this.monoOutput.subarray(0, frames2)
+      );
+      output[0].set(this.monoOutput.subarray(0, frames2));
+      return true;
+    }
+    const frames = this.ensureInterleavedCapacity(requestedFrames, requestedChannels);
+    const channels = requestedChannels;
+    for (let ch = 0; ch < channels; ch++) {
+      const src = input?.[ch];
+      const dst = this.planarChannels[ch];
+      if (!dst) {
+        continue;
+      }
+      if (src) {
+        dst.set(src.subarray(0, frames));
+      } else {
+        dst.fill(0, 0, frames);
+      }
+    }
+    this.changer.processPreparedPlanar(frames);
+    for (let ch = 0; ch < channels; ch++) {
+      const src = this.planarChannels[ch];
+      if (src) {
+        output[ch].set(src.subarray(0, frames));
+      }
+    }
+    return true;
+  }
+  destroy() {
+    if (this.destroyed) {
+      return;
+    }
+    this.destroyed = true;
+    this.changer.delete();
+  }
+  /**
+   * Returns the number of frames we can actually process given the
+   * pre-allocated capacity. If the host requests more frames than the
+   * worst-case block size declared at construction time, we clamp to the
+   * available capacity and warn once — we MUST NOT reallocate on the
+   * realtime audio thread.
+   */
+  ensureMonoCapacity(frames) {
+    const capacity = this.monoInput.length;
+    if (frames <= capacity) {
+      return frames;
+    }
+    if (!_SonareRealtimeVoiceChangerWorkletProcessor.warnedMonoOverflow) {
+      _SonareRealtimeVoiceChangerWorkletProcessor.warnedMonoOverflow = true;
+      console.warn(
+        `SonareRealtimeVoiceChangerWorkletProcessor: requested ${frames} mono frames exceeds pre-allocated capacity ${capacity}; clamping. Increase blockSize at construction time to avoid this.`
+      );
+    }
+    return capacity;
+  }
+  /**
+   * Same contract as ensureMonoCapacity but for the planar per-channel
+   * scratch. Returns the number of frames that fit in the available capacity.
+   */
+  ensureInterleavedCapacity(frames, channels) {
+    const capacity = this.planarChannels[0]?.length ?? 0;
+    if (frames <= capacity) {
+      return frames;
+    }
+    if (!_SonareRealtimeVoiceChangerWorkletProcessor.warnedInterleavedOverflow) {
+      _SonareRealtimeVoiceChangerWorkletProcessor.warnedInterleavedOverflow = true;
+      console.warn(
+        `SonareRealtimeVoiceChangerWorkletProcessor: requested ${frames}x${channels} planar frames exceeds pre-allocated capacity ${capacity}; clamping. Increase blockSize or channelCount at construction time to avoid this.`
+      );
+    }
+    return capacity;
+  }
+};
+_SonareRealtimeVoiceChangerWorkletProcessor.warnedMonoOverflow = false;
+_SonareRealtimeVoiceChangerWorkletProcessor.warnedInterleavedOverflow = false;
+var SonareRealtimeVoiceChangerWorkletProcessor = _SonareRealtimeVoiceChangerWorkletProcessor;
 function registerSonareWorkletProcessor(name = "sonare-worklet-processor") {
   const scope = globalThis;
   if (!scope.AudioWorkletProcessor || !scope.registerProcessor) {
@@ -1962,6 +2292,35 @@ function registerSonareWorkletProcessor(name = "sonare-worklet-processor") {
   }
   scope.registerProcessor(name, RegisteredSonareWorkletProcessor);
 }
+function registerSonareRealtimeVoiceChangerWorkletProcessor(name = "sonare-realtime-voice-changer-processor") {
+  const scope = globalThis;
+  if (!scope.AudioWorkletProcessor || !scope.registerProcessor) {
+    throw new Error("AudioWorkletProcessor is not available in this context.");
+  }
+  const Base = scope.AudioWorkletProcessor;
+  class RegisteredSonareRealtimeVoiceChangerWorkletProcessor extends Base {
+    constructor(options) {
+      super();
+      const port = this.port;
+      this.bridge = new SonareRealtimeVoiceChangerWorkletProcessor(options?.processorOptions ?? {});
+      const onMessage = (event) => {
+        if (isRealtimeVoiceChangerMessage(event.data)) {
+          this.bridge.receiveMessage(event.data);
+        }
+      };
+      if (port?.addEventListener) {
+        port.addEventListener("message", onMessage);
+        port.start?.();
+      } else if (port) {
+        port.onmessage = onMessage;
+      }
+    }
+    process(inputs, outputs) {
+      return this.bridge.process(inputs, outputs);
+    }
+  }
+  scope.registerProcessor(name, RegisteredSonareRealtimeVoiceChangerWorkletProcessor);
+}
 function registerSonareRealtimeEngineWorkletProcessor(name = "sonare-realtime-engine-processor") {
   const scope = globalThis;
   if (!scope.AudioWorkletProcessor || !scope.registerProcessor) {
@@ -2011,13 +2370,14 @@ function registerSonareRealtimeEngineWorkletProcessor(name = "sonare-realtime-en
         if (!options.rtModuleUrl) {
           throw new Error("rtModuleUrl is required for sonare-rt AudioWorklet runtime.");
         }
+        const rtModuleUrl = options.rtModuleUrl;
         const memory = new WebAssembly.Memory({ initial: 1024, maximum: 1024, shared: true });
         const globalFactory = globalThis.SonareRtModuleFactory;
-        const moduleFactory = globalFactory ? { default: globalFactory } : await import(options.rtModuleUrl);
+        const moduleFactory = globalFactory ? { default: globalFactory } : await import(rtModuleUrl);
         const module2 = await moduleFactory.default({
           wasmMemory: memory,
           wasmBinary: options.rtWasmBinary,
-          locateFile: (path) => options.rtModuleUrl.replace(/[^/]*$/, path)
+          locateFile: (path) => rtModuleUrl.replace(/[^/]*$/, path)
         });
         this.rtBridge = new SonareRtRealtimeEngineRuntime({
           module: module2,
@@ -2054,6 +2414,7 @@ export {
   SonareEngineTelemetryType,
   SonareRealtimeEngineNode,
   SonareRealtimeEngineWorkletProcessor,
+  SonareRealtimeVoiceChangerWorkletProcessor,
   SonareRtRealtimeEngineRuntime,
   SonareWorkletProcessor,
   createSonareEngineCommandRingBuffer,
@@ -2068,6 +2429,7 @@ export {
   readSonareMeterRingBuffer,
   readSonareSpectrumRingBuffer,
   registerSonareRealtimeEngineWorkletProcessor,
+  registerSonareRealtimeVoiceChangerWorkletProcessor,
   registerSonareWorkletProcessor,
   sonareEngineCommandRingBufferByteLength,
   sonareEngineTelemetryRingBufferByteLength,