@libraz/libsonare 1.7.2 → 1.8.0

package/src/validation.ts

@@ -1,3 +1,5 @@
+import { ErrorCode, SonareError } from './errors';
+
 /**
  * Per-call validation options accepted by guarded wrappers. Empty-buffer
  * checks are always performed; pass `{ validate: false }` to opt out of the
@@ -6,9 +8,11 @@
  * `{ validate: false }` only skips this JS-side pre-scan (which raises a
  * `RangeError` naming the exact offending index). It is NOT a way to push
  * non-finite samples into the core: the native layer always re-validates the
- * buffer (see `validate_offline_audio_input` in the C++ core), matching the C
- * ABI / Node / Python surfaces, so an NaN/Inf buffer still throws — just with a
- * generic native message instead of the indexed JS one.
+ * buffer — through `validate_offline_audio_input` for the offline-analysis
+ * entry points, and through the computation's own per-sample guard where a call
+ * takes no sample rate to validate against (the waveform bucket kernels) —
+ * matching the C ABI / Node / Python surfaces, so an NaN/Inf buffer still
+ * throws, just with a generic native message instead of the indexed JS one.
  */
 export interface ValidateOptions {
   validate?: boolean;
@@ -60,20 +64,68 @@ export function assertSamples(
   assertFiniteSamples(fnName, samples, validate, argName);
 }
 
+/**
+ * `assertSamples` restricted to the span a windowed entry point actually reads.
+ *
+ * The emptiness check still covers the whole buffer, and the reported index is
+ * the absolute one, so the message keeps naming the sample the caller passed.
+ * What narrows is the scan: a windowed call refuses a non-finite sample inside
+ * its frame and is indifferent to one outside it, which is the contract the C
+ * ABI states and the cost model it promises -- per call the scan is bounded by
+ * the frame, not by the length of the buffer being polled.
+ */
+export function assertSamplesInWindow(
+  fnName: string,
+  samples: ArrayLike<number>,
+  validate: boolean,
+  windowStart: number,
+  windowLength: number,
+  argName = 'samples',
+): void {
+  assertNonEmptySamples(fnName, samples, argName);
+  if (!validate) {
+    return;
+  }
+  // Floored and ceiled before use: a fractional offset is refused by the layer
+  // that owns it, but an index of 100.5 reads `undefined` out of the buffer and
+  // would be reported here as a non-finite sample that is not there.
+  const start = Math.min(Math.max(Math.floor(windowStart), 0), samples.length);
+  const stop = Math.min(start + Math.max(Math.ceil(windowLength), 0), samples.length);
+  for (let i = start; i < stop; i++) {
+    const v = samples[i] as number;
+    if (!Number.isFinite(v)) {
+      throw new RangeError(`${fnName}: ${argName} contains NaN or Inf at index ${i}`);
+    }
+  }
+}
+
 export function assertFiniteScalar(fnName: string, value: number, argName: string): void {
   if (!Number.isFinite(value)) {
     throw new RangeError(`${fnName}: ${argName} must be a finite number`);
   }
 }
 
-export function assertSampleRate(fnName: string, sampleRate: number): void {
-  if (
-    !Number.isInteger(sampleRate) ||
-    sampleRate < MIN_AUDIO_SAMPLE_RATE ||
-    sampleRate > MAX_AUDIO_SAMPLE_RATE
-  ) {
+/**
+ * A NaN gamma is the automatic-bandwidth sentinel the variable-Q transform
+ * documents, alongside a negative value, so only an infinity is out of domain.
+ */
+export function assertVqtGamma(fnName: string, gamma: number): void {
+  if (gamma === Number.POSITIVE_INFINITY || gamma === Number.NEGATIVE_INFINITY) {
+    throw new RangeError(`${fnName}: gamma must not be infinite`);
+  }
+}
+
+export function assertSampleRate(fnName: string, sampleRate: number, argName = 'sampleRate'): void {
+  // Two refusals, not one: 22050.7 sits inside the range, so reporting it as
+  // out of range names an argument that is not the one at fault. `argName` is
+  // the same point for a rate the caller spelled something else, such as a
+  // resampler's source and target.
+  if (!Number.isInteger(sampleRate)) {
+    throw new RangeError(`${fnName}: ${argName} must be an integer`);
+  }
+  if (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}]`,
+      `${fnName}: ${argName} out of supported range [${MIN_AUDIO_SAMPLE_RATE}, ${MAX_AUDIO_SAMPLE_RATE}]`,
     );
   }
 }
@@ -84,18 +136,240 @@ export function validateAudioBuffer(samples: Float32Array, sampleRate: number):
   assertSampleRate('Audio.fromBuffer', sampleRate);
 }
 
+/** Bounds of the native `int` every embind argument below is narrowed into. */
+export const C_INT_MIN = -2147483648;
+export const C_INT_MAX = 2147483647;
+
+/**
+ * Reject an argument embind's declared-`int` narrowing would wrap.
+ *
+ * A positional embind parameter declared `int` WRAPS rather than saturates, so
+ * a kernel of `2 ** 32` arrives as 0 and `2 ** 32 + 1` as 1 — both values the
+ * native guards accept, so the call succeeds having separated on a setting the
+ * caller never asked for. (The options-object path narrows through
+ * `checkedIntFromVal`, which refuses the same inputs in the module; this is the
+ * positional path's equivalent.)
+ *
+ * Reported as the branded `SonareError` carrying `InvalidParameter` rather than
+ * a `RangeError`, because the class follows what the rejection stands in for: a
+ * `RangeError` is this surface refusing an argument on its own authority, while
+ * this one pre-empts a native refusal the caller would have received under that
+ * code had the narrowing not wrapped the value into the accepted domain first.
+ * The agreement with the Node and Python surfaces is asserted by the Node
+ * package's `tests/narrowing-code-parity.test.ts`, which drives one value
+ * through all three — weakening this check turns that red.
+ */
+export function assertInt32(fnName: string, value: number, argName: string): void {
+  if (!Number.isInteger(value) || value < C_INT_MIN || value > C_INT_MAX) {
+    throw new SonareError(
+      ErrorCode.InvalidParameter,
+      'InvalidParameter',
+      `${fnName}: ${argName} must be an integer within the signed 32-bit range`,
+    );
+  }
+}
+
+/**
+ * Check both HPSS kernels before embind narrows them.
+ *
+ * Parity, positivity and the ceiling stay the core's to enforce, and it names
+ * the median filter that rejected the value. What cannot be deferred is the
+ * narrowing itself: a wrapped kernel arrives as a legal one and separates on it.
+ *
+ * These two arrive POSITIONALLY, so they never pass through the options-bag
+ * reader and inherit none of its checks. That is what separates this from
+ * {@link assertPercussiveSeparation}, which duplicates a reader check to improve
+ * a message; here there is no reader to duplicate.
+ */
+export function assertHpssKernels(
+  fnName: string,
+  kernelHarmonic: number,
+  kernelPercussive: number,
+): void {
+  assertInt32(fnName, kernelHarmonic, 'kernelHarmonic');
+  assertInt32(fnName, kernelPercussive, 'kernelPercussive');
+}
+
+function assertIntegralField(fnName: string, value: number, argName: string): void {
+  if (!Number.isInteger(value)) {
+    throw new SonareError(
+      ErrorCode.InvalidParameter,
+      'InvalidParameter',
+      `${fnName}: ${argName} must be an integer`,
+    );
+  }
+}
+
+/**
+ * Percussive-event separation fields, as the request objects carry them.
+ */
+export interface PercussiveSeparationFields {
+  nFft?: number;
+  hopLength?: number;
+  hpssKernelHarmonic?: number;
+  hpssKernelPercussive?: number;
+}
+
+/**
+ * Check the percussive-event separation's framing and kernels for integrality.
+ *
+ * All four fields reach the module through one options-bag reader, which now
+ * refuses a fractional value itself, so this is the diagnostic rather than the
+ * guarantee: it fires first and names the function, where the reader can only
+ * name the field. Both reject the same set, so they cannot disagree about an
+ * input — only about how the message reads. Do not narrow this to fields the
+ * reader misses; there are none, and a check scoped to a gap that no longer
+ * exists is how a stale justification outlives its divergence.
+ *
+ * The fields are iterated rather than named at each call site so a new one is
+ * visible here. Absence means the default, so an omitted field is not resolved.
+ */
+export function assertPercussiveSeparation(
+  fnName: string,
+  options: PercussiveSeparationFields,
+): void {
+  const fields = ['nFft', 'hopLength', 'hpssKernelHarmonic', 'hpssKernelPercussive'] as const;
+  for (const field of fields) {
+    const value = options[field];
+    if (value !== undefined) {
+      assertIntegralField(fnName, value, field);
+    }
+  }
+}
+
 export function assertNonNegativeInteger(fnName: string, value: number, argName: string): void {
   if (!Number.isInteger(value) || value < 0) {
     throw new RangeError(`${fnName}: ${argName} must be a non-negative integer`);
   }
 }
 
+/** Integer strictly greater than zero, up to the native `int` ceiling. */
 export function assertPositiveInteger(fnName: string, value: number, argName: string): void {
-  if (!Number.isInteger(value) || value <= 0) {
+  // Two refusals, not one: 512.7 is positive, so reporting it as non-positive
+  // names a property it has. The ceiling travels with the sign rather than with
+  // integrality, because both describe a value the native `int` can carry.
+  if (!Number.isInteger(value)) {
+    throw new RangeError(`${fnName}: ${argName} must be an integer`);
+  }
+  if (value <= 0 || value > C_INT_MAX) {
     throw new RangeError(`${fnName}: ${argName} must be a positive integer`);
   }
 }
 
+/**
+ * Split "not an integer" into the two mistakes it can be: `TypeError` when the
+ * value is not a `number` at all, `RangeError` when it is a number but not
+ * integral -- the right-type, wrong-domain half of the same message.
+ *
+ * `Number.isInteger` alone answers both, which is why a single check reads as
+ * sufficient; what it cannot do is say which one happened, and a caller can act
+ * only on the mistake they made. The classes are the contract on this surface,
+ * so a sibling argument in the same call must not report a fraction differently
+ * from this one.
+ */
+export function assertIntegerValue(
+  fnName: string,
+  value: unknown,
+  argName: string,
+): asserts value is number {
+  if (typeof value !== 'number') {
+    throw new TypeError(`${fnName}: ${argName} must be an integer`);
+  }
+  if (!Number.isInteger(value)) {
+    throw new RangeError(`${fnName}: ${argName} must be an integer`);
+  }
+}
+
+/** Even integer in `[min, max]`, for an FFT-style size where only parity matters. */
+export function assertEvenIntegerAtLeast(
+  fnName: string,
+  value: number,
+  argName: string,
+  min: number,
+  max: number,
+): void {
+  // Range and parity are separate refusals: 2 ** 31 is already even, so telling
+  // its caller the value must be even names a property it has.
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new RangeError(`${fnName}: ${argName} must be an integer in [${min}, ${max}]`);
+  }
+  if (value % 2 !== 0) {
+    throw new RangeError(`${fnName}: ${argName} must be an even integer`);
+  }
+}
+
+/** General integer-in-`[min, max]` check, for a bound {@link assertU7}/{@link assertNibble} don't cover. */
+export function assertBoundedInteger(
+  fnName: string,
+  value: number,
+  argName: string,
+  min: number,
+  max: number,
+): void {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new RangeError(`${fnName}: ${argName} must be an integer in [${min}, ${max}]`);
+  }
+}
+
+export function assertU7(fnName: string, value: number, argName: string): number {
+  if (!Number.isInteger(value) || value < 0 || value > 127) {
+    throw new RangeError(`${fnName}: ${argName} must be an integer in [0, 127]`);
+  }
+  return value;
+}
+
+export function assertNibble(fnName: string, value: number, argName: string): number {
+  if (!Number.isInteger(value) || value < 0 || value > 15) {
+    throw new RangeError(`${fnName}: ${argName} must be an integer in [0, 15]`);
+  }
+  return value;
+}
+
+export function assertU32(fnName: string, value: number, argName: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+    throw new RangeError(`${fnName}: ${argName} must be an integer in [0, 4294967295]`);
+  }
+}
+
+/**
+ * Convert a caller-supplied index array to `Int32Array`, refusing any element
+ * the conversion would change rather than folding it.
+ *
+ * `Int32Array.from(values, Math.trunc)` turns the sample index `1000.7` into
+ * `1000` and `2 ** 31` into `-2 ** 31`. The C ABI takes `const int*`, so both
+ * arrive as values nothing downstream can separate from ones the caller chose.
+ * An `Int32Array` is returned as-is: its elements are already exact.
+ */
+export function toInt32Array(
+  fnName: string,
+  values: Int32Array | ArrayLike<number>,
+  argName: string,
+): Int32Array {
+  if (values instanceof Int32Array) {
+    return values;
+  }
+  const out = new Int32Array(values.length);
+  for (let i = 0; i < values.length; i++) {
+    const element = values[i];
+    // The element shape of `assertIntegerValue`, and it splits the same way: the
+    // class says whether the entry was the wrong type or the wrong domain, and a
+    // sibling element in the same array must not report a fraction differently.
+    if (typeof element !== 'number') {
+      throw new TypeError(`${fnName}: ${argName}[${i}] must be an integer`);
+    }
+    if (!Number.isInteger(element)) {
+      throw new RangeError(`${fnName}: ${argName}[${i}] must be an integer`);
+    }
+    if (element < C_INT_MIN || element > C_INT_MAX) {
+      throw new RangeError(
+        `${fnName}: ${argName}[${i}] must be an integer in [${C_INT_MIN}, ${C_INT_MAX}]`,
+      );
+    }
+    out[i] = element;
+  }
+  return out;
+}
+
 export function assertInterleavedSamples(
   fnName: string,
   samples: ArrayLike<number>,

package/src/web_midi.ts

@@ -1,4 +1,5 @@
 import type { MidiCcBindOptions } from './realtime_engine';
+import { assertNibble } from './validation';
 
 export interface WebMidiEngine {
   bindMidiCc(
@@ -394,12 +395,6 @@ function readU7(data: ArrayLike<number>, index: number): number {
   return value;
 }
 
-function assertNibble(fnName: string, value: number, field: string): void {
-  if (!Number.isInteger(value) || value < 0 || value > 15) {
-    throw new RangeError(`${fnName}: ${field} must be an integer in [0, 15]`);
-  }
-}
-
 function iterInputs(access: MidiAccessLike): Iterable<[string, MidiInputLike]> {
   return access.inputs instanceof Map ? access.inputs.entries() : access.inputs;
 }

package/src/worker.ts

@@ -98,8 +98,16 @@ function cancelledError(): SonareError {
  */
 export function installOfflineWorkerEndpoint(endpoint: OfflineWorkerEndpoint): void {
   const cancelled = new Set<number>();
+  // IDs with a run() in flight, from message dispatch to its finally block.
+  // A cancel naming an ID outside this set has nothing left to cancel -- the
+  // run already settled, or never started -- and must not be recorded, or it
+  // leaks a Set entry no later message ever clears.
+  const inFlight = new Set<number>();
 
   const run = async (message: OfflineWorkerRunMessage): Promise<void> => {
+    // Synchronous: runs before this async function's first `await`, so it is
+    // visible to the listener below before any other message can be handled.
+    inFlight.add(message.id);
     const cancelFlag = message.cancelBuffer ? new Int32Array(message.cancelBuffer) : undefined;
     const isCancelled = (): boolean =>
       cancelled.has(message.id) || (cancelFlag !== undefined && Atomics.load(cancelFlag, 0) !== 0);
@@ -107,19 +115,22 @@ export function installOfflineWorkerEndpoint(endpoint: OfflineWorkerEndpoint): v
       endpoint.postMessage({ type: 'sonare:offline-progress', id: message.id, progress, stage });
       return isCancelled() ? false : undefined;
     };
-
     try {
       await init();
       if (isCancelled()) {
         throw cancelledError();
       }
 
+      // `cancel` is a separate channel from `onProgress`: the native call polls
+      // it and never reads what the progress callback returns, so passing only
+      // onProgress left a running operation no way to learn it was cancelled.
       let result: unknown;
       switch (message.operation) {
         case 'analyze':
           result = analyzeWithProgress({
             ...(message.request as unknown as MusicAnalyzeRequest),
             onProgress,
+            cancel: isCancelled,
           });
           break;
         case 'detectBpm':
@@ -135,12 +146,14 @@ export function installOfflineWorkerEndpoint(endpoint: OfflineWorkerEndpoint): v
           result = masterAudio({
             ...(message.request as unknown as MasterAudioRequest),
             onProgress,
+            cancel: isCancelled,
           });
           break;
         case 'masterAudioStereo':
           result = masterAudioStereo({
             ...(message.request as unknown as MasterAudioStereoRequest),
             onProgress,
+            cancel: isCancelled,
           });
           break;
       }
@@ -159,13 +172,16 @@ export function installOfflineWorkerEndpoint(endpoint: OfflineWorkerEndpoint): v
       });
     } finally {
       cancelled.delete(message.id);
+      inFlight.delete(message.id);
     }
   };
 
   endpoint.addEventListener('message', (event) => {
     const message = event.data;
     if (message.type === 'sonare:offline-cancel') {
-      cancelled.add(message.id);
+      if (inFlight.has(message.id)) {
+        cancelled.add(message.id);
+      }
       return;
     }
     void run(message);

package/src/worklet/audio_types.ts

@@ -1,2 +1,39 @@
 export type WorkletInput = readonly (readonly Float32Array[])[];
 export type WorkletOutput = Float32Array[][];
+
+/**
+ * Copies one plane per output channel. Shared by every worklet output — the
+ * engine's program and cue buses and the voice changer — so they cannot drift
+ * in their padding behaviour. Allocation-free.
+ *
+ * A host output wider than the engine's plane count is mapped the way Web Audio
+ * up-mixes rather than by padding with a copy of plane 0:
+ * - A single plane fans out to every output channel, so a mono engine driving a
+ *   stereo host stays centred instead of hard-panned left.
+ * - With two or more planes, an output channel past the last plane is silence.
+ *   Duplicating plane 0 into it would put the left signal in a rear or centre
+ *   channel and add correlated energy the engine never produced.
+ *
+ * Everything the source does not fill is zeroed — the tail past `frames`, and
+ * the remainder of a plane shorter than `frames` — so no sample of the previous
+ * block survives into this one.
+ */
+export function copyPlanesToOutput(
+  output: Float32Array[],
+  planes: readonly Float32Array[],
+  frames: number,
+): void {
+  const monoFanOut = planes.length === 1;
+  for (let ch = 0; ch < output.length; ch++) {
+    const target = output[ch];
+    const source = monoFanOut ? planes[0] : planes[ch];
+    let copied = 0;
+    if (source) {
+      copied = Math.min(target.length, frames, source.length);
+      target.set(source.subarray(0, copied));
+    }
+    if (copied < target.length) {
+      target.fill(0, copied);
+    }
+  }
+}