@octoseq/mir 0.1.0-main.0d2814e

package/dist/types-BE3py4fZ.d.ts

@@ -0,0 +1,83 @@
+type MirBackend = "cpu" | "gpu";
+type MirRunTimings = {
+    totalMs: number;
+    cpuMs?: number;
+    gpuMs?: number;
+};
+type MirRunMeta = {
+    backend: MirBackend;
+    usedGpu: boolean;
+    timings: MirRunTimings;
+};
+type Mir1DResult = {
+    kind: "1d";
+    times: Float32Array;
+    values: Float32Array;
+    meta: MirRunMeta;
+};
+type Mir2DResult = {
+    kind: "2d";
+    times: Float32Array;
+    data: Float32Array[];
+    meta: MirRunMeta;
+};
+type MirEvent = {
+    time: number;
+    strength: number;
+    index: number;
+};
+type MirEventsResult = {
+    kind: "events";
+    times: Float32Array;
+    events: MirEvent[];
+    meta: MirRunMeta;
+};
+type MirResult = Mir1DResult | Mir2DResult | MirEventsResult;
+type MirFunctionId = "spectralCentroid" | "spectralFlux" | "melSpectrogram" | "onsetEnvelope" | "onsetPeaks" | "hpssHarmonic" | "hpssPercussive" | "mfcc" | "mfccDelta" | "mfccDeltaDelta";
+type MirRunRequest = {
+    fn: MirFunctionId;
+    spectrogram?: {
+        fftSize: number;
+        hopSize: number;
+        window: "hann";
+    };
+    mel?: {
+        nMels: number;
+        fMin?: number;
+        fMax?: number;
+    };
+    backend?: MirBackend;
+    onset?: {
+        smoothMs?: number;
+        diffMethod?: "rectified" | "abs";
+        useLog?: boolean;
+    };
+    peakPick?: {
+        minIntervalSec?: number;
+        threshold?: number;
+        adaptiveFactor?: number;
+    };
+    hpss?: {
+        timeMedian?: number;
+        freqMedian?: number;
+        spectrogram?: {
+            fftSize: number;
+            hopSize: number;
+            window: "hann";
+        };
+    };
+    mfcc?: {
+        nCoeffs?: number;
+        spectrogram?: {
+            fftSize: number;
+            hopSize: number;
+            window: "hann";
+        };
+    };
+};
+type MirAudioPayload = {
+    sampleRate: number;
+    mono: Float32Array;
+};
+
+export type { MirBackend as M, MirRunTimings as a, MirRunMeta as b, Mir1DResult as c, Mir2DResult as d, MirResult as e, MirFunctionId as f, MirRunRequest as g, MirAudioPayload as h };

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@octoseq/mir",
+    "version": "0.1.0-main.0d2814e",
+    "description": "WebGPU-accelerated Music Information Retrieval (MIR) library (skeleton)",
+    "license": "MIT",
+    "private": false,
+    "type": "module",
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "src"
+    ],
+    "exports": {
+        ".": {
+            "types": "./src/index.ts",
+            "import": "./src/index.ts"
+        },
+        "./runner/runMir": {
+            "types": "./src/runner/runMir.ts",
+            "import": "./src/runner/runMir.ts"
+        },
+        "./runner/workerProtocol": {
+            "types": "./src/runner/workerProtocol.ts",
+            "import": "./src/runner/workerProtocol.ts"
+        }
+    },
+    "main": "./dist/index.js",
+    "types": "./src/index.ts",
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "typecheck": "tsc -p tsconfig.json --noEmit",
+        "lint": "eslint -c eslint.config.mjs .",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "devDependencies": {
+        "@types/node": "latest",
+        "eslint": "latest",
+        "tsup": "latest",
+        "typescript": "latest",
+        "vitest": "latest"
+    },
+    "dependencies": {
+        "fft.js": "^4.0.4"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/rewbs/octoseq.git",
+        "directory": "packages/mir"
+    }
+}

package/src/dsp/fft.ts

@@ -0,0 +1,22 @@
+/**
+ * Windowing utilities.
+ *
+ * Note:
+ * - The FFT implementation previously lived in this file.
+ * - As of v0.1.x we use `fft.js` behind an internal backend abstraction (see `fftBackend.ts`).
+ * - We keep only the window function here because it is part of the STFT behaviour that downstream
+ *   stages depend on.
+ */
+
+// (Complex FFT implementation removed; kept intentionally empty.)
+
+export function hannWindow(size: number): Float32Array {
+    const w = new Float32Array(size);
+    // Periodic Hann (common for STFT overlap-add).
+    for (let n = 0; n < size; n++) {
+        w[n] = 0.5 - 0.5 * Math.cos((2 * Math.PI * n) / size);
+    }
+    return w;
+}
+
+// FFT and magnitude helpers removed.

package/src/dsp/fftBackend.ts

@@ -0,0 +1,53 @@
+/**
+ * Internal FFT backend abstraction.
+ *
+ * Why:
+ * - The rest of the STFT pipeline should not care about the FFT implementation.
+ * - We want to be able to swap this layer for a future WebGPU FFT without touching callers.
+ */
+
+export type FftComplexOutput = {
+    /** Full-length FFT output (length = fftSize). */
+    real: Float32Array;
+    /** Full-length FFT output (length = fftSize). */
+    imag: Float32Array;
+};
+
+export interface FftBackend {
+    readonly fftSize: number;
+
+    /**
+     * Forward FFT for real-valued input.
+     *
+     * Contract:
+     * - input length must equal fftSize.
+     * - returns full complex spectrum (not just rfft half-spectrum) to keep the interface generic.
+     *
+     * Scaling:
+     * - No normalisation is applied (same convention as typical FFT libraries, incl. fft.js).
+     * - Therefore magnitude values scale roughly with window sum and fftSize.
+     *   This matches the previous hand-rolled FFT behaviour and is close to librosa's default
+     *   `np.abs(np.fft.rfft(...))` magnitude semantics (also unnormalised).
+     */
+    forwardReal(input: Float32Array): FftComplexOutput;
+}
+
+/**
+ * Internal cache to avoid re-creating FFT plans for the same size.
+ * Safe for Web Workers (per-worker module instance). Not shared across threads.
+ */
+const backendCache = new Map<number, FftBackend>();
+
+export function getFftBackend(fftSize: number): FftBackend {
+    const existing = backendCache.get(fftSize);
+    if (existing) return existing;
+
+    // Note: ESM static import is OK in browsers and Web Workers.
+    // The cache ensures the plan is only created once per fftSize per worker.
+    const created = createFftJsBackend(fftSize);
+    backendCache.set(fftSize, created);
+    return created;
+}
+
+// Implemented in separate file to keep the public surface minimal.
+import { createFftJsBackend } from "./fftBackendFftjs";

package/src/dsp/fftBackendFftjs.ts

@@ -0,0 +1,60 @@
+/**
+ * `fft.js` backend.
+ *
+ * Notes:
+ * - We intentionally keep this file small and self-contained so we can replace it later with a GPU FFT.
+ * - `fft.js` performs an unnormalised forward FFT (same convention as our previous radix-2 code).
+ * - We allocate the plan once per fftSize and reuse internal buffers across frames.
+ */
+
+import FFT from "fft.js";
+
+import type { FftBackend, FftComplexOutput } from "./fftBackend";
+
+export function createFftJsBackend(fftSize: number): FftBackend {
+    if (!Number.isFinite(fftSize) || fftSize <= 0 || (fftSize | 0) !== fftSize) {
+        throw new Error("@octoseq/mir: fftSize must be a positive integer");
+    }
+
+    const fft = new FFT(fftSize);
+
+    // `fft.js` uses interleaved complex arrays [re0, im0, re1, im1, ...]
+    // It accepts input for realTransform as a real array of length N.
+    const inReal = new Float32Array(fftSize);
+    const outComplexInterleaved = fft.createComplexArray() as unknown as Float32Array;
+
+    const outReal = new Float32Array(fftSize);
+    const outImag = new Float32Array(fftSize);
+
+    return {
+        fftSize,
+        forwardReal(frame: Float32Array): FftComplexOutput {
+            if (frame.length !== fftSize) {
+                throw new Error(
+                    `@octoseq/mir: FFT input length (${frame.length}) must equal fftSize (${fftSize})`
+                );
+            }
+
+            // Copy to stable buffer to avoid fft.js mutating user-owned arrays.
+            inReal.set(frame);
+
+            // Real-input FFT.
+            // `realTransform(out, data)` fills out with interleaved complex spectrum.
+            // `completeSpectrum(out)` fills the negative frequencies so we get full N complex bins.
+            fft.realTransform(outComplexInterleaved as unknown as number[], inReal as unknown as number[]);
+            fft.completeSpectrum(outComplexInterleaved as unknown as number[]);
+
+            // De-interleave into (real, imag) arrays.
+            // Note: we keep full spectrum even though most consumers only need 0..N/2.
+            for (let k = 0; k < fftSize; k++) {
+                const re = outComplexInterleaved[2 * k] ?? 0;
+                const im = outComplexInterleaved[2 * k + 1] ?? 0;
+                // Canonicalise -0 -> +0 so silence tests and downstream comparisons are stable.
+                outReal[k] = re === 0 ? 0 : re;
+                outImag[k] = im === 0 ? 0 : im;
+            }
+
+            return { real: outReal, imag: outImag };
+        }
+    };
+}

package/src/dsp/hpss.ts

@@ -0,0 +1,152 @@
+import type { Spectrogram } from "./spectrogram";
+
+export type SpectrogramLike2D = {
+    times: Float32Array;
+    bins: number;
+    frames: number;
+    magnitudes: Float32Array[]; // [frame][bin]
+};
+
+export type HpssOptions = {
+    /** Median filter kernel size along time axis (frames). Must be odd. */
+    timeMedian?: number;
+    /** Median filter kernel size along frequency axis (bins). Must be odd. */
+    freqMedian?: number;
+    /** If true, use soft masks; else hard mask. */
+    softMask?: boolean;
+    /** Cancellation hook for long loops. */
+    isCancelled?: () => boolean;
+};
+
+function assertOddPositiveInt(name: string, v: number): void {
+    if (!Number.isFinite(v) || v <= 0 || (v | 0) !== v) {
+        throw new Error(`@octoseq/mir: ${name} must be a positive integer`);
+    }
+    if (v % 2 !== 1) {
+        throw new Error(`@octoseq/mir: ${name} must be odd`);
+    }
+}
+
+function medianOfWindow(values: Float32Array): number {
+    // Small-kernel median: copy + sort. CPU-heavy but fine for v0.1.
+    // Isolated here so a future GPU / histogram-based median can replace it.
+    const arr = Array.from(values);
+    arr.sort((a, b) => a - b);
+    const mid = arr.length >>> 1;
+    return arr[mid] ?? 0;
+}
+
+function medianFilterTime(spec: Spectrogram, kTime: number, options: HpssOptions): Float32Array[] {
+    const nFrames = spec.times.length;
+    const nBins = (spec.fftSize >>> 1) + 1;
+
+    const half = kTime >>> 1;
+    const out: Float32Array[] = new Array(nFrames);
+
+    const window = new Float32Array(kTime);
+
+    for (let t = 0; t < nFrames; t++) {
+        if (options.isCancelled?.()) throw new Error("@octoseq/mir: cancelled");
+
+        const row = new Float32Array(nBins);
+        for (let k = 0; k < nBins; k++) {
+            // Build temporal window for bin k.
+            for (let i = -half, wi = 0; i <= half; i++, wi++) {
+                const tt = Math.max(0, Math.min(nFrames - 1, t + i));
+                const mags = spec.magnitudes[tt];
+                window[wi] = mags ? (mags[k] ?? 0) : 0;
+            }
+            row[k] = medianOfWindow(window);
+        }
+        out[t] = row;
+    }
+
+    return out;
+}
+
+function medianFilterFreq(spec: Spectrogram, kFreq: number, options: HpssOptions): Float32Array[] {
+    const nFrames = spec.times.length;
+    const nBins = (spec.fftSize >>> 1) + 1;
+
+    const half = kFreq >>> 1;
+    const out: Float32Array[] = new Array(nFrames);
+
+    const window = new Float32Array(kFreq);
+
+    for (let t = 0; t < nFrames; t++) {
+        if (options.isCancelled?.()) throw new Error("@octoseq/mir: cancelled");
+
+        const mags = spec.magnitudes[t] ?? new Float32Array(nBins);
+        const row = new Float32Array(nBins);
+
+        for (let k = 0; k < nBins; k++) {
+            for (let i = -half, wi = 0; i <= half; i++, wi++) {
+                const kk = Math.max(0, Math.min(nBins - 1, k + i));
+                window[wi] = mags[kk] ?? 0;
+            }
+            row[k] = medianOfWindow(window);
+        }
+
+        out[t] = row;
+    }
+
+    return out;
+}
+
+export function hpss(spec: Spectrogram, options: HpssOptions = {}): { harmonic: SpectrogramLike2D; percussive: SpectrogramLike2D } {
+    const timeMedian = options.timeMedian ?? 17;
+    const freqMedian = options.freqMedian ?? 17;
+    assertOddPositiveInt("options.timeMedian", timeMedian);
+    assertOddPositiveInt("options.freqMedian", freqMedian);
+
+    const nFrames = spec.times.length;
+    const nBins = (spec.fftSize >>> 1) + 1;
+
+    // Median along time -> harmonic estimate
+    const H = medianFilterTime(spec, timeMedian, options);
+    // Median along freq -> percussive estimate
+    const P = medianFilterFreq(spec, freqMedian, options);
+
+    const harmonic: Float32Array[] = new Array(nFrames);
+    const percussive: Float32Array[] = new Array(nFrames);
+
+    const soft = options.softMask ?? true;
+    const eps = 1e-12;
+
+    for (let t = 0; t < nFrames; t++) {
+        if (options.isCancelled?.()) throw new Error("@octoseq/mir: cancelled");
+
+        const mags = spec.magnitudes[t] ?? new Float32Array(nBins);
+        const hRow = H[t] ?? new Float32Array(nBins);
+        const pRow = P[t] ?? new Float32Array(nBins);
+
+        const outH = new Float32Array(nBins);
+        const outP = new Float32Array(nBins);
+
+        for (let k = 0; k < nBins; k++) {
+            const x = mags[k] ?? 0;
+            const h = hRow[k] ?? 0;
+            const p = pRow[k] ?? 0;
+
+            if (soft) {
+                const denom = Math.max(eps, h + p);
+                const mh = h / denom;
+                const mp = p / denom;
+                outH[k] = x * mh;
+                outP[k] = x * mp;
+            } else {
+                const isH = h >= p;
+                outH[k] = isH ? x : 0;
+                outP[k] = isH ? 0 : x;
+            }
+        }
+
+        harmonic[t] = outH;
+        percussive[t] = outP;
+    }
+
+    return {
+        harmonic: { times: spec.times, bins: nBins, frames: nFrames, magnitudes: harmonic },
+        percussive: { times: spec.times, bins: nBins, frames: nFrames, magnitudes: percussive },
+    };
+}

package/src/dsp/hpssGpu.ts

@@ -0,0 +1,101 @@
+import type { Spectrogram } from "./spectrogram";
+import type { SpectrogramLike2D, HpssOptions } from "./hpss";
+
+import type { MirGPU } from "../gpu/context";
+import { gpuHpssMasks } from "../gpu/hpssMasks";
+
+export type HpssGpuResult = {
+    harmonic: SpectrogramLike2D;
+    percussive: SpectrogramLike2D;
+    gpuMs: number;
+};
+
+function flattenMagnitudes(mags: Float32Array[], nFrames: number, nBins: number): Float32Array {
+    const flat = new Float32Array(nFrames * nBins);
+    for (let t = 0; t < nFrames; t++) {
+        const row = mags[t] ?? new Float32Array(nBins);
+        flat.set(row, t * nBins);
+    }
+    return flat;
+}
+
+function assertFiniteMask(name: string, v: number): void {
+    if (!Number.isFinite(v)) {
+        throw new Error(`@octoseq/mir: GPU HPSS produced non-finite ${name}`);
+    }
+}
+
+/**
+ * GPU-accelerated HPSS (mask estimation on GPU, apply on CPU).
+ *
+ * Important:
+ * - CPU median HPSS remains the reference implementation.
+ * - GPU uses fixed median-of-9 approximation, regardless of CPU options.
+ *   Mapping (documented): CPU defaults (17) -> GPU fixed (9).
+ */
+export async function hpssGpu(
+    spec: Spectrogram,
+    gpu: MirGPU,
+    options: HpssOptions = {}
+): Promise<HpssGpuResult> {
+    const nFrames = spec.times.length;
+    const nBins = (spec.fftSize >>> 1) + 1;
+
+    if (options.isCancelled?.()) throw new Error("@octoseq/mir: cancelled");
+
+    // Flatten spectrogram magnitudes for GPU.
+    const magsFlat = flattenMagnitudes(spec.magnitudes, nFrames, nBins);
+
+    const soft = options.softMask ?? true;
+
+    const masks = await gpuHpssMasks(gpu, {
+        nFrames,
+        nBins,
+        magsFlat,
+        softMask: soft,
+    });
+
+    if (options.isCancelled?.()) throw new Error("@octoseq/mir: cancelled");
+
+    const hMask = masks.value.harmonicMaskFlat;
+    const pMask = masks.value.percussiveMaskFlat;
+
+    const harmonic: Float32Array[] = new Array(nFrames);
+    const percussive: Float32Array[] = new Array(nFrames);
+
+    // Apply masks on CPU to preserve exact output shape/type.
+    // We also do a best-effort cancellation check per frame.
+    for (let t = 0; t < nFrames; t++) {
+        if (options.isCancelled?.()) throw new Error("@octoseq/mir: cancelled");
+
+        const mags = spec.magnitudes[t] ?? new Float32Array(nBins);
+        const outH = new Float32Array(nBins);
+        const outP = new Float32Array(nBins);
+
+        const base = t * nBins;
+        for (let k = 0; k < nBins; k++) {
+            const x = mags[k] ?? 0;
+            const mh = hMask[base + k] ?? 0;
+            const mp = pMask[base + k] ?? 0;
+
+            assertFiniteMask("mask", mh);
+            assertFiniteMask("mask", mp);
+
+            // masks are expected in [0,1] (kernel outputs that), but clamp defensively.
+            const ch = Math.max(0, Math.min(1, mh));
+            const cp = Math.max(0, Math.min(1, mp));
+
+            outH[k] = x * ch;
+            outP[k] = x * cp;
+        }
+
+        harmonic[t] = outH;
+        percussive[t] = outP;
+    }
+
+    return {
+        harmonic: { times: spec.times, bins: nBins, frames: nFrames, magnitudes: harmonic },
+        percussive: { times: spec.times, bins: nBins, frames: nFrames, magnitudes: percussive },
+        gpuMs: masks.timing.gpuSubmitToReadbackMs,
+    };
+}