@libraz/libsonare 1.8.0 → 1.8.1

package/dist/index.js

@@ -624,13 +624,30 @@ function alignTakeToReference(request) {
 }
 
 // src/_effects_common.ts
-function toVoicedFloat32(voiced) {
+function toVoicedFloat32(fnName, voiced) {
+  if (!(voiced instanceof Int32Array || voiced instanceof Uint8Array || voiced instanceof Float32Array || Array.isArray(voiced))) {
+    throw new TypeError(
+      `${fnName}: voiced must be an Int32Array, Uint8Array, Float32Array, number[], or boolean[]`
+    );
+  }
   const out = new Float32Array(voiced.length);
   for (let index = 0; index < voiced.length; index += 1) {
-    out[index] = voiced[index] ? 1 : 0;
+    const value = voiced[index];
+    if (typeof value !== "number" && typeof value !== "boolean") {
+      throw new TypeError(`${fnName}: voiced array entries must be numbers or booleans`);
+    }
+    out[index] = value ? 1 : 0;
   }
   return out;
 }
+function assertPitchTrackLengths(fnName, f0Hz, voiced, voicedProb) {
+  if (voiced != null && voiced.length !== f0Hz.length) {
+    throw new RangeError(`${fnName}: voiced must have the same length as f0Hz`);
+  }
+  if (voiced == null && voicedProb != null && voicedProb.length !== f0Hz.length) {
+    throw new RangeError(`${fnName}: voicedProb must have the same length as f0Hz`);
+  }
+}
 
 // src/effects_note_ops.ts
 function requireModule() {
@@ -639,13 +656,9 @@ function requireModule() {
 function assertNoteTrack(fnName, request) {
   assertSamples(fnName, request.samples, request.validate !== false);
   assertSampleRate(fnName, request.sampleRate);
-  if (request.voiced && request.voiced.length !== request.f0Hz.length) {
-    throw new RangeError(`${fnName}: voiced length must match f0Hz length`);
-  }
-  if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
-    throw new RangeError(`${fnName}: voicedProb length must match f0Hz length`);
-  }
-  return request.voiced ? toVoicedFloat32(request.voiced) : void 0;
+  const voicedF32 = request.voiced == null ? void 0 : toVoicedFloat32(fnName, request.voiced);
+  assertPitchTrackLengths(fnName, request.f0Hz, request.voiced, request.voicedProb);
+  return voicedF32;
 }
 function noteStretch(samples, sampleRate = 22050, options = {}) {
   const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
@@ -675,20 +688,46 @@ function extractNotes(request) {
     request.samples,
     request.sampleRate,
     request.f0Hz,
-    request.voicedProb,
+    request.voiced == null ? request.voicedProb ?? void 0 : void 0,
     voicedF32,
     request.frameRate,
     request
   );
 }
 function renderNotes(request) {
-  assertSamples("renderNotes", request.samples, request.validate !== false);
   assertSampleRate("renderNotes", request.sampleRate);
-  return requireModule().renderNotes(request.samples, request.sampleRate, request.notes, request);
+  if (!Array.isArray(request.notes)) {
+    throw new TypeError("renderNotes: notes must be an array");
+  }
+  const f0Hz = request.f0Hz;
+  if (f0Hz !== void 0 && !(f0Hz instanceof Float32Array)) {
+    throw new TypeError("renderNotes: f0Hz must be a Float32Array");
+  }
+  if (f0Hz !== void 0) {
+    assertFiniteScalar("renderNotes", request.frameRate, "frameRate");
+  }
+  const { voiced: publicVoiced, ...withoutVoiced } = request;
+  const voiced = publicVoiced == null ? void 0 : toVoicedFloat32("renderNotes", publicVoiced);
+  if (publicVoiced != null && f0Hz === void 0) {
+    throw new RangeError("renderNotes: voiced requires f0Hz");
+  }
+  if (f0Hz !== void 0) {
+    assertPitchTrackLengths("renderNotes", f0Hz, publicVoiced);
+  }
+  assertSamples("renderNotes", request.samples, request.validate !== false);
+  const options = { ...withoutVoiced, voiced };
+  return requireModule().renderNotes(request.samples, request.sampleRate, request.notes, options);
 }
 function decomposeNotePitch(request) {
+  if (!(request.f0Hz instanceof Float32Array)) {
+    throw new TypeError("decomposeNotePitch: f0Hz must be a Float32Array");
+  }
+  assertFiniteScalar("decomposeNotePitch", request.frameRate, "frameRate");
+  const voiced = request.voiced == null ? void 0 : toVoicedFloat32("decomposeNotePitch", request.voiced);
+  assertPitchTrackLengths("decomposeNotePitch", request.f0Hz, request.voiced);
   return requireModule().decomposeNotePitch(
     request.f0Hz,
+    voiced,
     request.frameRate,
     request.medianHz,
     request.vibratoCutoffHz ?? 0
@@ -700,7 +739,7 @@ function splitNote(request) {
     request.samples,
     request.sampleRate,
     request.f0Hz,
-    request.voicedProb,
+    request.voiced == null ? request.voicedProb ?? void 0 : void 0,
     voicedF32,
     request.frameRate,
     request.notes,
@@ -715,7 +754,7 @@ function mergeNotes(request) {
     request.samples,
     request.sampleRate,
     request.f0Hz,
-    request.voicedProb,
+    request.voiced == null ? request.voicedProb ?? void 0 : void 0,
     voicedF32,
     request.frameRate,
     request.notes,
@@ -912,13 +951,13 @@ function pitchCorrectToMidiTimevarying(samples, f0Hz, targetMidi, sampleRate = 2
     ...options
   } : samples;
   assertSamples("pitchCorrectToMidiTimevarying", request.samples, request.validate !== false);
-  if (request.voiced && request.voiced.length !== request.f0Hz.length) {
-    throw new RangeError("pitchCorrectToMidiTimevarying: voiced length must match f0Hz length");
-  }
-  if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
-    throw new RangeError("pitchCorrectToMidiTimevarying: voicedProb length must match f0Hz length");
-  }
-  const voicedF32 = request.voiced ? toVoicedFloat32(request.voiced) : void 0;
+  const voicedF32 = request.voiced == null ? void 0 : toVoicedFloat32("pitchCorrectToMidiTimevarying", request.voiced);
+  assertPitchTrackLengths(
+    "pitchCorrectToMidiTimevarying",
+    request.f0Hz,
+    request.voiced,
+    request.voicedProb
+  );
   return requireModule5().pitchCorrectToMidiTimevarying(
     request.samples,
     request.sampleRate ?? 22050,
@@ -926,21 +965,23 @@ function pitchCorrectToMidiTimevarying(samples, f0Hz, targetMidi, sampleRate = 2
     request.targetMidi,
     request.hopLength ?? 512,
     voicedF32,
-    request.voicedProb
+    request.voiced == null ? request.voicedProb ?? void 0 : void 0
   );
 }
 function pitchCorrectTimevarying(samples, f0Hz, sampleRate = 22050, hopLength = 512, options = {}) {
   const request = samples instanceof Float32Array ? { samples, f0Hz, sampleRate, hopLength, ...options } : samples;
   assertSamples("pitchCorrectTimevarying", request.samples, request.validate !== false);
-  if (request.voiced && request.voiced.length !== request.f0Hz.length) {
-    throw new RangeError("pitchCorrectTimevarying: voiced length must match f0Hz length");
-  }
-  if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
-    throw new RangeError("pitchCorrectTimevarying: voicedProb length must match f0Hz length");
-  }
+  const voicedF32 = request.voiced == null ? void 0 : toVoicedFloat32("pitchCorrectTimevarying", request.voiced);
+  assertPitchTrackLengths(
+    "pitchCorrectTimevarying",
+    request.f0Hz,
+    request.voiced,
+    request.voicedProb
+  );
   const nativeOptions = {
     ...request,
-    voiced: request.voiced ? toVoicedFloat32(request.voiced) : void 0
+    voiced: voicedF32,
+    voicedProb: request.voiced == null ? request.voicedProb ?? void 0 : void 0
   };
   return requireModule5().pitchCorrectTimevarying(
     request.samples,
@@ -1369,6 +1410,32 @@ function masteringPairProcess(processorName, source, reference, sampleRate = 220
     request.params ?? {}
   );
 }
+function masteringPairProcessStereo(processorName, sourceLeft, sourceRight, referenceLeft, referenceRight, sampleRate = 22050, params = {}) {
+  const request = typeof processorName === "string" ? {
+    processorName,
+    sourceLeft,
+    sourceRight,
+    referenceLeft,
+    referenceRight,
+    sampleRate,
+    params
+  } : processorName;
+  if (request.sourceLeft.length !== request.sourceRight.length) {
+    throw new Error("Source left and right channel lengths must match.");
+  }
+  if (request.referenceLeft.length !== request.referenceRight.length) {
+    throw new Error("Reference left and right channel lengths must match.");
+  }
+  return requireModule8().masteringPairProcessStereo(
+    request.processorName,
+    request.sourceLeft,
+    request.sourceRight,
+    request.referenceLeft,
+    request.referenceRight,
+    request.sampleRate ?? 22050,
+    request.params ?? {}
+  );
+}
 function masteringPairAnalyze(analysisName, source, reference, sampleRate = 22050, params = {}) {
   const request = typeof analysisName === "string" ? {
     analysisName,
@@ -1392,6 +1459,21 @@ function masteringAbMatchLoudness(request) {
     request.sampleRate ?? 22050
   );
 }
+function masteringAbMatchLoudnessStereo(request) {
+  if (request.sourceLeft.length !== request.sourceRight.length) {
+    throw new Error("Source left and right channel lengths must match.");
+  }
+  if (request.referenceLeft.length !== request.referenceRight.length) {
+    throw new Error("Reference left and right channel lengths must match.");
+  }
+  return requireModule8().masteringAbMatchLoudnessStereo(
+    request.sourceLeft,
+    request.sourceRight,
+    request.referenceLeft,
+    request.referenceRight,
+    request.sampleRate ?? 22050
+  );
+}
 function masteringStereoAnalyze(analysisName, left, right, sampleRate = 22050, params = {}) {
   const request = typeof analysisName === "string" ? {
     analysisName,
@@ -2029,7 +2111,7 @@ function decomposeWithInit(s, nFeatures = 0, nFrames = 0, nComponents = 0, nIter
   return requireModule16().decomposeWithInit(s, nFeatures, nFrames, nComponents, nIter, beta, init2);
 }
 function decomposeStems(request) {
-  return requireModule16().decomposeStems(request.samples, request.sampleRate, {
+  return requireModule16().decomposeStems(request.samples, request.sampleRate ?? 22050, {
     nComponents: request.nComponents,
     nFft: request.nFft,
     hopLength: request.hopLength,
@@ -6674,7 +6756,10 @@ var RealtimeEngine = class _RealtimeEngine {
   /**
    * Route a destination's (track lane's) MIDI to the external output queue
    * instead of the internal instrument rack, so the track plays an external
-   * device. Clearing it restores internal-synth playback.
+   * device. Clearing it restores internal-synth playback. Control-thread only.
+   * The change takes effect at the next processed block; switching a
+   * destination's route first releases its notes and resets its controllers
+   * through the old route, and drops its pending MIDI-FX events. Single writer.
    */
   setMidiDestinationExternal(destinationId, external) {
     this.native.setMidiDestinationExternal(destinationId, external);
@@ -6828,8 +6913,11 @@ var RealtimeEngine = class _RealtimeEngine {
   /**
    * Queue an immediate (live) MIDI SysEx frame to a MIDI destination. `data` is
    * the full message including the leading 0xF0 and trailing 0xF7 (1..512
-   * bytes). `renderFrame` is the frame to fire at, or -1 for immediate. Mirrors
-   * the Node/Python/C-ABI `pushMidiSysex`.
+   * bytes). `renderFrame` is the frame to fire at, or -1 for immediate. Throws
+   * `InvalidParameter` when the destination instrument cannot prepare
+   * the SysEx (retrying cannot help), and `OutOfMemory` when the payload
+   * slots or the command queue are full (retry after a processed block).
+   * Mirrors the Node/Python/C-ABI `pushMidiSysex`.
    */
   pushMidiSysex(destinationId, data, renderFrame = -1) {
     this.native.pushMidiSysex(destinationId, data, renderFrame);
@@ -6852,12 +6940,30 @@ var RealtimeEngine = class _RealtimeEngine {
   getTransportState() {
     return this.native.getTransportState();
   }
+  /** Queues an integrated-loudness reset; short-term and momentary windows are retained. */
+  resetMasterLoudnessMeter(renderFrame = -1) {
+    this.native.resetMasterLoudnessMeter(renderFrame);
+  }
+  /** Reads the immutable factory value for a resolved insert parameter id. */
+  insertParameterConstructedValue(paramId) {
+    return this.native.insertParameterConstructedValue(paramId);
+  }
   play(renderFrame = -1) {
     this.native.play(renderFrame);
   }
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   stop(renderFrame = -1) {
     this.native.stop(renderFrame);
   }
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   seekSample(timelineSample, renderFrame = -1) {
     this.native.seekSample(timelineSample, renderFrame);
   }
@@ -6882,6 +6988,11 @@ var RealtimeEngine = class _RealtimeEngine {
   applyCommandsDueNowPreservingFuture() {
     this.native.applyCommandsDueNowPreservingFuture();
   }
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   seekPpq(ppq, renderFrame = -1) {
     this.native.seekPpq(ppq, renderFrame);
   }
@@ -6901,6 +7012,11 @@ var RealtimeEngine = class _RealtimeEngine {
   sampleAtPpq(ppq) {
     return Number(this.native.sampleAtPpq(ppq));
   }
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   setLoop(startPpq, endPpq, enabled = true) {
     this.native.setLoop(startPpq, endPpq, enabled);
   }
@@ -6995,10 +7111,10 @@ var RealtimeEngine = class _RealtimeEngine {
         if (typeof lane === "number") {
           return { trackId: lane };
         }
-        if (!lane.sends) {
-          return lane;
-        }
-        return { ...lane, sends: _RealtimeEngine.normalizeSends(lane.sends) };
+        return {
+          ...lane,
+          sends: lane.sends ? _RealtimeEngine.normalizeSends(lane.sends) : void 0
+        };
       })
     );
   }
@@ -7011,9 +7127,10 @@ var RealtimeEngine = class _RealtimeEngine {
   }
   setTrackBuses(buses) {
     this.native.setTrackBuses(
-      Array.isArray(buses) ? buses.map(
-        (bus) => bus.sends ? { ...bus, sends: _RealtimeEngine.normalizeSends(bus.sends) } : bus
-      ) : buses
+      Array.isArray(buses) ? buses.map((bus) => ({
+        ...bus,
+        sends: bus.sends ? _RealtimeEngine.normalizeSends(bus.sends) : void 0
+      })) : buses
     );
   }
   /**
@@ -7167,6 +7284,16 @@ var RealtimeEngine = class _RealtimeEngine {
    * 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.
+   *
+   * The returned id uses the track's current positional lane selector. When
+   * `setTrackLanes` successfully changes lane order or membership, the engine
+   * remaps already queued and published track automation by track id, but it
+   * cannot update a numeric id retained by the caller. Re-resolve every track
+   * insert id after such a topology change before passing it to
+   * `setAutomationLane`, `setParameter`, or `setParameterSmoothed`. Use
+   * `setTrackStripInsertParamByName` when the operation needs a stable track
+   * identity. Master and bus insert ids are separate and are not invalidated by
+   * track-lane changes.
    */
   resolveTrackInsertAutomationId(trackId, insertIndex, paramName) {
     return this.native.resolveTrackInsertAutomationId(trackId, insertIndex, paramName);
@@ -7493,6 +7620,12 @@ var RealtimeEngine = class _RealtimeEngine {
   meterScratchRenderFrame() {
     return Number(this.native.meterScratchRenderFrame());
   }
+  meterScratchInputPeakDbL() {
+    return this.native.meterScratchInputPeakDbL();
+  }
+  meterScratchInputPeakDbR() {
+    return this.native.meterScratchInputPeakDbR();
+  }
   meterScratchValue(field) {
     return this.native.meterScratchValue(field);
   }
@@ -7502,9 +7635,10 @@ var RealtimeEngine = class _RealtimeEngine {
   /**
    * Drains pending meter telemetry as per-plane (wide) records for a surround
    * target. Use this for a surround mix target; {@link drainMeterTelemetry}
-   * stays the stereo fast path. The two share one queue — call only one per
-   * target. The live AudioWorklet path owns the queue via the stereo drain, so
-   * this wide drain is for an offline (non-worklet) engine instance; per-plane
+   * stays the stereo fast path. The two share one queue and each consumes every
+   * target's records, so an engine uses only one of them. The live AudioWorklet
+   * path owns the queue via the stereo drain, so this wide drain is for an
+   * offline (non-worklet) engine instance; per-plane
    * surround meters are not delivered over the live worklet meter ring.
    */
   drainMeterTelemetryWide(maxRecords = 1024) {
@@ -7942,47 +8076,60 @@ var Mixer = class _Mixer {
    * after {@link delete}.
    */
   createRealtimeBuffer() {
-    const stripCount = this.stripCount();
-    let leftInputs = [];
-    let rightInputs = [];
+    const leftInputs = [];
+    const rightInputs = [];
     let outLeft = this.mixer.outputLeftView();
     let outRight = this.mixer.outputRightView();
+    let acquiredStripCount = -1;
+    const viewsDetached = () => outLeft.byteLength === 0 || outRight.byteLength === 0;
     const acquire = () => {
-      leftInputs = [];
-      rightInputs = [];
-      for (let index = 0; index < stripCount; index++) {
+      const stripCount = this.stripCount();
+      const detached = viewsDetached();
+      if (detached) {
+        leftInputs.length = 0;
+        rightInputs.length = 0;
+      } else {
+        leftInputs.length = Math.min(leftInputs.length, stripCount);
+        rightInputs.length = Math.min(rightInputs.length, stripCount);
+      }
+      for (let index = leftInputs.length; index < stripCount; index++) {
         leftInputs.push(this.mixer.inputLeftView(index));
+      }
+      for (let index = rightInputs.length; index < stripCount; index++) {
         rightInputs.push(this.mixer.inputRightView(index));
       }
-      outLeft = this.mixer.outputLeftView();
-      outRight = this.mixer.outputRightView();
+      if (detached) {
+        outLeft = this.mixer.outputLeftView();
+        outRight = this.mixer.outputRightView();
+      }
+      acquiredStripCount = stripCount;
     };
     acquire();
-    const reacquireIfDetached = () => {
-      if (outLeft.byteLength === 0 || (leftInputs[0]?.byteLength ?? 1) === 0) {
+    const acquireIfNeeded = () => {
+      if (acquiredStripCount !== this.stripCount() || viewsDetached()) {
         acquire();
       }
     };
     return {
       get leftInputs() {
-        reacquireIfDetached();
+        acquireIfNeeded();
         return leftInputs;
       },
       get rightInputs() {
-        reacquireIfDetached();
+        acquireIfNeeded();
         return rightInputs;
       },
       get outLeft() {
-        reacquireIfDetached();
+        acquireIfNeeded();
         return outLeft;
       },
       get outRight() {
-        reacquireIfDetached();
+        acquireIfNeeded();
         return outRight;
       },
-      process: (numSamples = outLeft.length) => {
-        reacquireIfDetached();
-        this.mixer.processPreparedStereo(numSamples);
+      process: (numSamples) => {
+        acquireIfNeeded();
+        this.mixer.processPreparedStereo(numSamples ?? outLeft.length);
       }
     };
   }
@@ -8782,6 +8929,13 @@ var StreamingMasteringChain = class {
   reset() {
     this.chain.reset();
   }
+  /**
+   * Set one realtime-safe full-chain parameter at a serialized block boundary.
+   * Structural, disabled-stage and unknown parameters are rejected.
+   */
+  setParameter(key, value) {
+    this.chain.setParameter(key, value);
+  }
   /** Total reported latency in samples across all active processors. */
   latencySamples() {
     return this.chain.latencySamples();
@@ -9756,6 +9910,7 @@ export {
   masterAudioWithProgress,
   mastering,
   masteringAbMatchLoudness,
+  masteringAbMatchLoudnessStereo,
   masteringAmpPresetCatalog,
   masteringAssistantSuggest,
   masteringAssistantSuggestChain,
@@ -9777,6 +9932,7 @@ export {
   masteringPairAnalysisNames,
   masteringPairAnalyze,
   masteringPairProcess,
+  masteringPairProcessStereo,
   masteringPairProcessorNames,
   masteringPlatformNames,
   masteringPresetNames,