@libraz/libsonare 1.7.2 → 1.8.0

package/dist/validation.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Per-call validation options accepted by guarded wrappers. Empty-buffer
+ * checks are always performed; pass `{ validate: false }` to opt out of the
+ * O(n) NaN/Inf scan on hot paths.
+ *
+ * `{ 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 — 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;
+}
+/**
+ * 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 declare const MIN_AUDIO_SAMPLE_RATE = 8000;
+export declare const MAX_AUDIO_SAMPLE_RATE = 384000;
+export declare function assertSamples(fnName: string, samples: ArrayLike<number>, validate: boolean, argName?: string): void;
+/**
+ * `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 declare function assertSamplesInWindow(fnName: string, samples: ArrayLike<number>, validate: boolean, windowStart: number, windowLength: number, argName?: string): void;
+export declare function assertFiniteScalar(fnName: string, value: number, argName: string): void;
+/**
+ * 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 declare function assertVqtGamma(fnName: string, gamma: number): void;
+export declare function assertSampleRate(fnName: string, sampleRate: number, argName?: string): void;
+/** Validate and retain the public Audio.fromBuffer construction contract. */
+export declare function validateAudioBuffer(samples: Float32Array, sampleRate: number): void;
+/** Bounds of the native `int` every embind argument below is narrowed into. */
+export declare const C_INT_MIN = -2147483648;
+export declare 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 declare function assertInt32(fnName: string, value: number, argName: string): void;
+/**
+ * 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 declare function assertHpssKernels(fnName: string, kernelHarmonic: number, kernelPercussive: number): void;
+/**
+ * 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 declare function assertPercussiveSeparation(fnName: string, options: PercussiveSeparationFields): void;
+export declare function assertNonNegativeInteger(fnName: string, value: number, argName: string): void;
+/** Integer strictly greater than zero, up to the native `int` ceiling. */
+export declare function assertPositiveInteger(fnName: string, value: number, argName: string): void;
+/**
+ * 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 declare function assertIntegerValue(fnName: string, value: unknown, argName: string): asserts value is number;
+/** Even integer in `[min, max]`, for an FFT-style size where only parity matters. */
+export declare function assertEvenIntegerAtLeast(fnName: string, value: number, argName: string, min: number, max: number): void;
+/** General integer-in-`[min, max]` check, for a bound {@link assertU7}/{@link assertNibble} don't cover. */
+export declare function assertBoundedInteger(fnName: string, value: number, argName: string, min: number, max: number): void;
+export declare function assertU7(fnName: string, value: number, argName: string): number;
+export declare function assertNibble(fnName: string, value: number, argName: string): number;
+export declare function assertU32(fnName: string, value: number, argName: string): void;
+/**
+ * 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 declare function toInt32Array(fnName: string, values: Int32Array | ArrayLike<number>, argName: string): Int32Array;
+export declare function assertInterleavedSamples(fnName: string, samples: ArrayLike<number>, channels: number, validate: boolean): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/dist/web_midi.d.ts

@@ -0,0 +1,77 @@
+import type { MidiCcBindOptions } from './realtime_engine';
+export interface WebMidiEngine {
+    bindMidiCc(channel: number, controller: number, paramId: number, options?: MidiCcBindOptions): void;
+    setMidiInputSource(destinationId?: number): void;
+    clearMidiInputSource(): void;
+    pushMidiInputNoteOn(group: number, channel: number, note: number, velocity: number, time?: number): void;
+    pushMidiInputNoteOff(group: number, channel: number, note: number, velocity?: number, time?: number): void;
+    pushMidiInputCc(group: number, channel: number, controller: number, value: number, time?: number): void;
+}
+type MidiInputState = 'connected' | 'disconnected';
+interface MidiPortLike {
+    id: string;
+    name?: string | null;
+    manufacturer?: string | null;
+    state?: MidiInputState;
+}
+interface MidiMessageEventLike {
+    data: ArrayLike<number>;
+    timeStamp?: number;
+    receivedTime?: number;
+    target?: MidiPortLike;
+    currentTarget?: MidiPortLike;
+}
+interface MidiInputLike extends MidiPortLike {
+    type?: 'input';
+    onmidimessage: ((event: MidiMessageEventLike) => void) | null;
+    addEventListener?: (type: 'midimessage', listener: (event: MidiMessageEventLike) => void) => void;
+    removeEventListener?: (type: 'midimessage', listener: (event: MidiMessageEventLike) => void) => void;
+}
+interface MidiConnectionEventLike {
+    port?: MidiPortLike | null;
+}
+interface MidiAccessLike {
+    inputs: Map<string, MidiInputLike> | Iterable<[string, MidiInputLike]>;
+    onstatechange: ((event: MidiConnectionEventLike) => void) | null;
+    addEventListener?: (type: 'statechange', listener: (event: MidiConnectionEventLike) => void) => void;
+    removeEventListener?: (type: 'statechange', listener: (event: MidiConnectionEventLike) => void) => void;
+}
+export interface WebMidiCcBinding {
+    channel: number;
+    controller: number;
+    paramId: number;
+    options?: MidiCcBindOptions;
+}
+export interface WebMidiInputInfo {
+    id: string;
+    name: string;
+    manufacturer: string;
+    state: MidiInputState;
+}
+export interface BindWebMidiOptions {
+    /** Realtime-engine MIDI destination receiving the live input source. Default `0`. */
+    destinationId?: number;
+    /** UMP group used for MIDI 1.0 channel voice events. Default `0`. */
+    group?: number;
+    /** Restrict binding to specific Web MIDI input ids. Omit or empty = all connected inputs. */
+    inputIds?: readonly string[];
+    /** Request SysEx-capable access from the browser. Default `false`. */
+    sysex?: boolean;
+    /** Request software ports from the browser where supported. Default `true`. */
+    software?: boolean;
+    /** Bind CC-to-parameter mappings before ports are connected. */
+    ccBindings?: readonly WebMidiCcBinding[];
+    /** Convert a Web MIDI event timestamp to engine port-time samples. */
+    timestampToSamples?: (eventTimeMs: number) => number;
+    /** Observe hot-plug updates after the helper rebinds matching inputs. */
+    onInputsChanged?: (inputs: WebMidiInputInfo[]) => void;
+}
+export interface WebMidiBinding {
+    access: MidiAccessLike;
+    inputs(): WebMidiInputInfo[];
+    close(): void;
+}
+export declare function isWebMidiAvailable(): boolean;
+export declare function bindWebMidi(engine: WebMidiEngine, options?: BindWebMidiOptions): Promise<WebMidiBinding>;
+export {};
+//# sourceMappingURL=web_midi.d.ts.map

package/dist/web_midi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_midi.d.ts","sourceRoot":"","sources":["../src/web_midi.ts"],"names":[],"mappings":"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"}

package/dist/worker.d.ts

@@ -1,46 +1,3 @@
-/**
- * Internal structured-clone protocol for the offline Web Worker bridge.
- *
- * Keep this deliberately limited to one-shot operations. Embind handles own
- * native resources and cannot safely cross a worker boundary.
- */
-type OfflineWorkerOperation = 'analyze' | 'detectBpm' | 'detectKey' | 'detectChords' | 'masterAudio' | 'masterAudioStereo';
-interface OfflineWorkerRunMessage {
-    type: 'sonare:offline-run';
-    id: number;
-    operation: OfflineWorkerOperation;
-    request: Record<string, unknown>;
-    /** A shared flag lets cancellation reach synchronous WASM progress callbacks. */
-    cancelBuffer?: SharedArrayBuffer;
-}
-interface OfflineWorkerCancelMessage {
-    type: 'sonare:offline-cancel';
-    id: number;
-}
-type OfflineWorkerRequestMessage = OfflineWorkerRunMessage | OfflineWorkerCancelMessage;
-interface OfflineWorkerProgressMessage {
-    type: 'sonare:offline-progress';
-    id: number;
-    progress: number;
-    stage: string;
-}
-interface OfflineWorkerResultMessage {
-    type: 'sonare:offline-result';
-    id: number;
-    result: unknown;
-}
-interface OfflineWorkerErrorMessage {
-    type: 'sonare:offline-error';
-    id: number;
-    error: {
-        name: string;
-        message: string;
-        code?: number;
-        codeName?: string;
-    };
-}
-type OfflineWorkerResponseMessage = OfflineWorkerProgressMessage | OfflineWorkerResultMessage | OfflineWorkerErrorMessage;
-
 /**
  * Offline one-shot operations hosted inside a dedicated Web Worker.
  *
@@ -49,9 +6,10 @@ type OfflineWorkerResponseMessage = OfflineWorkerProgressMessage | OfflineWorker
  * bound to one JavaScript realm, so moving them across a Worker boundary would
  * make ownership and `delete()` semantics unsound.
  */
-
+import type { OfflineWorkerRequestMessage, OfflineWorkerResponseMessage } from './worker_protocol';
+export type { OfflineWorkerOperation } from './worker_protocol';
 /** Minimal endpoint shared by browser Workers and the Node worker-thread test bridge. */
-interface OfflineWorkerEndpoint {
+export interface OfflineWorkerEndpoint {
     postMessage(message: OfflineWorkerResponseMessage, transfer?: Transferable[]): void;
     addEventListener(type: 'message', listener: (event: MessageEvent<OfflineWorkerRequestMessage>) => void): void;
 }
@@ -60,6 +18,5 @@ interface OfflineWorkerEndpoint {
  * the Node `worker_threads` test adapter; browsers install it automatically
  * when this module is loaded as a Worker entry point.
  */
-declare function installOfflineWorkerEndpoint(endpoint: OfflineWorkerEndpoint): void;
-
-export { type OfflineWorkerEndpoint, type OfflineWorkerOperation, installOfflineWorkerEndpoint };
+export declare function installOfflineWorkerEndpoint(endpoint: OfflineWorkerEndpoint): void;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,KAAK,EAEV,2BAA2B,EAC3B,4BAA4B,EAE7B,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,yFAAyF;AACzF,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,OAAO,EAAE,4BAA4B,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IACpF,gBAAgB,CACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,2BAA2B,CAAC,KAAK,IAAI,GACnE,IAAI,CAAC;CACT;AAyDD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CA0FlF"}

package/dist/worker.js

@@ -6,7 +6,21 @@ var SonareError = class extends Error {
     this.code = code;
     this.codeName = codeName;
   }
+  /**
+   * Brand-based `instanceof`: an error that carries the shape narrows here even
+   * when it is not literally an instance of this class. That is not a
+   * hypothetical — an error posted from the analysis worker arrives as a
+   * structured clone with its prototype gone, which a prototype-based
+   * `instanceof` would silently miss. Delegates to {@link isSonareError} so the
+   * two never disagree.
+   */
+  static [Symbol.hasInstance](value) {
+    return isSonareError(value);
+  }
 };
+function isSonareError(value) {
+  return value instanceof Error && value.name === "SonareError" && typeof value.code === "number";
+}
 
 // src/module_state.ts
 var wrappedModule = null;
@@ -34,6 +48,11 @@ function makeSonareError(raw, thrown) {
       message = info.message || message;
     }
   } catch {
+  } finally {
+    try {
+      raw.sonareReleaseException(thrown);
+    } catch {
+    }
   }
   return new SonareError(code, codeName, message);
 }
@@ -54,6 +73,10 @@ function wrapModuleErrors(raw) {
     if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer || value instanceof Promise) {
       return value;
     }
+    const proto = Object.getPrototypeOf(value);
+    if (Array.isArray(value) || proto === Object.prototype || proto === null) {
+      return value;
+    }
     const objectValue = value;
     const cached = objectCache.get(objectValue);
     if (cached) {
@@ -150,6 +173,46 @@ function getSonareModule() {
   return wrappedModule;
 }
 
+// src/codes.ts
+function resolveOrdinalInRange(value, min, max, enumName) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
+  }
+  return value;
+}
+function resolveEnumOrdinal(value, values, enumName) {
+  if (typeof value === "number") {
+    const ordinals = Object.values(values);
+    const ordinal = resolveOrdinalInRange(
+      value,
+      Math.min(...ordinals),
+      Math.max(...ordinals),
+      enumName
+    );
+    if (!ordinals.includes(ordinal)) {
+      throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
+    }
+    return ordinal;
+  }
+  if (typeof value === "string") {
+    const ordinal = values[value];
+    if (ordinal !== void 0) {
+      return ordinal;
+    }
+  }
+  throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
+}
+var AUTOMATION_CURVE_VALUES = {
+  linear: 0,
+  exponential: 1,
+  hold: 2,
+  "s-curve": 3
+};
+var PROJECT_AUTOMATION_CURVE_VALUES = {
+  ...AUTOMATION_CURVE_VALUES,
+  scurve: 3
+};
+
 // src/validation.ts
 var MIN_AUDIO_SAMPLE_RATE = 8e3;
 var MAX_AUDIO_SAMPLE_RATE = 384e3;
@@ -173,10 +236,13 @@ function assertSamples(fnName, samples, validate, argName = "samples") {
   assertNonEmptySamples(fnName, samples, argName);
   assertFiniteSamples(fnName, samples, validate, argName);
 }
-function assertSampleRate(fnName, sampleRate) {
-  if (!Number.isInteger(sampleRate) || sampleRate < MIN_AUDIO_SAMPLE_RATE || sampleRate > MAX_AUDIO_SAMPLE_RATE) {
+function assertSampleRate(fnName, sampleRate, argName = "sampleRate") {
+  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}]`
     );
   }
 }
@@ -284,36 +350,6 @@ function masterAudioStereo(left, right = void 0, sampleRate = 22050, presetName
   );
 }
 
-// src/codes.ts
-function resolveOrdinalInRange(value, min, max, enumName) {
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
-    throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
-  }
-  return value;
-}
-function resolveEnumOrdinal(value, values, enumName) {
-  if (typeof value === "number") {
-    const ordinals = Object.values(values);
-    const ordinal = resolveOrdinalInRange(
-      value,
-      Math.min(...ordinals),
-      Math.max(...ordinals),
-      enumName
-    );
-    if (!ordinals.includes(ordinal)) {
-      throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
-    }
-    return ordinal;
-  }
-  if (typeof value === "string") {
-    const ordinal = values[value];
-    if (ordinal !== void 0) {
-      return ordinal;
-    }
-  }
-  throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
-}
-
 // src/public_types_music.ts
 var PitchClass = {
   C: 0,
@@ -426,6 +462,7 @@ function convertChordAnalysisResult(wasm) {
       quality: c.quality,
       start: c.start,
       end: c.end,
+      duration: c.end - c.start,
       confidence: c.confidence,
       name: c.name
     }))
@@ -464,6 +501,10 @@ function convertAnalysisResult(wasm) {
     timeSignatureCandidates: wasm.timeSignatureCandidates,
     beatTimes,
     beats: wasm.beats,
+    downbeatIndices: wasm.downbeatIndices,
+    downbeatPhase: wasm.downbeatPhase,
+    beatObservations: wasm.beatObservations,
+    beatLocalBpm: wasm.beatLocalBpm,
     chords: wasm.chords.map((c) => ({
       root: c.root,
       bass: c.bass,
@@ -472,8 +513,10 @@ function convertAnalysisResult(wasm) {
       quality: c.quality,
       start: c.start,
       end: c.end,
+      duration: c.end - c.start,
       confidence: c.confidence,
-      name: c.name
+      name: c.name,
+      romanNumeral: c.romanNumeral
     })),
     sections: wasm.sections.map((s) => ({
       type: s.type,
@@ -546,12 +589,13 @@ function detectChords(samples, sampleRate = 22050, options = {}) {
     request.keyRoot ?? PitchClass.C,
     request.keyMode ?? Mode.Major,
     request.detectInversions ?? false,
-    chordChromaMethodValue(request.chromaMethod ?? "stft")
+    chordChromaMethodValue(request.chromaMethod ?? "stft"),
+    request.tuning ?? 0
   );
   return convertChordAnalysisResult(result);
 }
-function analyzeWithProgress(samples, sampleRate = 22050, onProgress) {
-  const request = samples instanceof Float32Array ? { samples, sampleRate, onProgress } : samples;
+function analyzeWithProgress(samples, sampleRate = 22050, onProgress, options) {
+  const request = samples instanceof Float32Array ? { samples, sampleRate, onProgress, options } : samples;
   validateAnalysisInput(
     "analyzeWithProgress",
     request.samples,
@@ -561,6 +605,7 @@ function analyzeWithProgress(samples, sampleRate = 22050, onProgress) {
   const result = requireModule2().analyzeWithProgress(
     request.samples,
     request.sampleRate ?? 22050,
+    request.options ?? {},
     request.onProgress ?? (() => {
     }),
     request.cancel ?? (() => false)
@@ -646,7 +691,9 @@ function cancelledError() {
 }
 function installOfflineWorkerEndpoint(endpoint2) {
   const cancelled = /* @__PURE__ */ new Set();
+  const inFlight = /* @__PURE__ */ new Set();
   const run = async (message) => {
+    inFlight.add(message.id);
     const cancelFlag = message.cancelBuffer ? new Int32Array(message.cancelBuffer) : void 0;
     const isCancelled = () => cancelled.has(message.id) || cancelFlag !== void 0 && Atomics.load(cancelFlag, 0) !== 0;
     const onProgress = (progress, stage) => {
@@ -663,7 +710,8 @@ function installOfflineWorkerEndpoint(endpoint2) {
         case "analyze":
           result = analyzeWithProgress({
             ...message.request,
-            onProgress
+            onProgress,
+            cancel: isCancelled
           });
           break;
         case "detectBpm":
@@ -678,13 +726,15 @@ function installOfflineWorkerEndpoint(endpoint2) {
         case "masterAudio":
           result = masterAudio({
             ...message.request,
-            onProgress
+            onProgress,
+            cancel: isCancelled
           });
           break;
         case "masterAudioStereo":
           result = masterAudioStereo({
             ...message.request,
-            onProgress
+            onProgress,
+            cancel: isCancelled
           });
           break;
       }
@@ -703,12 +753,15 @@ function installOfflineWorkerEndpoint(endpoint2) {
       });
     } finally {
       cancelled.delete(message.id);
+      inFlight.delete(message.id);
     }
   };
   endpoint2.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);