@octoseq/mir 0.1.0-main.0d2814e

package/src/dsp/spectral.ts

@@ -0,0 +1,95 @@
+import type { Spectrogram } from "./spectrogram";
+
+/**
+ * Spectral centroid per frame (Hz).
+ *
+ * Output is aligned 1:1 with `spec.times`.
+ */
+export function spectralCentroid(spec: Spectrogram): Float32Array {
+    const nFrames = spec.times.length;
+    const out = new Float32Array(nFrames);
+
+    const nBins = (spec.fftSize >>> 1) + 1;
+    const binHz = spec.sampleRate / spec.fftSize;
+
+    for (let t = 0; t < nFrames; t++) {
+        const mags = spec.magnitudes[t];
+        if (!mags) {
+            out[t] = 0;
+            continue;
+        }
+
+        let num = 0;
+        let den = 0;
+
+        // DC..Nyquist inclusive.
+        for (let k = 0; k < nBins; k++) {
+            const m = mags[k] ?? 0;
+            const f = k * binHz;
+            num += f * m;
+            den += m;
+        }
+
+        out[t] = den > 0 ? num / den : 0;
+    }
+
+    return out;
+}
+
+/**
+ * Spectral flux per frame (unitless).
+ *
+ * Definition used here:
+ * - L1 distance between successive *normalised* magnitude spectra.
+ * - First frame flux is 0.
+ *
+ * Output is aligned 1:1 with `spec.times`.
+ */
+export function spectralFlux(spec: Spectrogram): Float32Array {
+    const nFrames = spec.times.length;
+    const out = new Float32Array(nFrames);
+
+    const nBins = (spec.fftSize >>> 1) + 1;
+
+    let prev: Float32Array | null = null;
+
+    for (let t = 0; t < nFrames; t++) {
+        const mags = spec.magnitudes[t];
+        if (!mags) {
+            out[t] = 0;
+            prev = null;
+            continue;
+        }
+
+        // Normalise to reduce sensitivity to overall level.
+        let sum = 0;
+        for (let k = 0; k < nBins; k++) sum += mags[k] ?? 0;
+
+        if (sum <= 0) {
+            out[t] = 0;
+            prev = null;
+            continue;
+        }
+
+        const cur = new Float32Array(nBins);
+        const inv = 1 / sum;
+        for (let k = 0; k < nBins; k++) cur[k] = (mags[k] ?? 0) * inv;
+
+        if (!prev) {
+            out[t] = 0;
+            prev = cur;
+            continue;
+        }
+
+        let flux = 0;
+        for (let k = 0; k < nBins; k++) {
+            const d = (cur[k] ?? 0) - (prev[k] ?? 0);
+            flux += Math.abs(d);
+        }
+
+        out[t] = flux;
+        prev = cur;
+    }
+
+    return out;
+}

package/src/dsp/spectrogram.ts

@@ -0,0 +1,176 @@
+import type { MirGPU } from "../gpu/context";
+
+import { hannWindow } from "./fft";
+import { getFftBackend } from "./fftBackend";
+
+// AudioBufferLike is re-exported from the package root.
+// Keeping this local type avoids importing from ../index (which can create circular deps).
+export type AudioBufferLike = {
+    sampleRate: number;
+    getChannelData(channel: number): Float32Array;
+    numberOfChannels: number;
+};
+
+export type SpectrogramConfig = {
+    fftSize: number;
+    hopSize: number;
+    window: "hann";
+};
+
+export type SpectrogramOptions = {
+    /** Optional cancellation hook; checked once per frame. */
+    isCancelled?: () => boolean;
+};
+
+export type Spectrogram = {
+    sampleRate: number;
+    fftSize: number;
+    hopSize: number;
+    times: Float32Array; // seconds (center of each frame)
+    magnitudes: Float32Array[]; // [frame][bin]
+};
+
+function assertPositiveInt(name: string, value: number): void {
+    if (!Number.isFinite(value) || value <= 0 || (value | 0) !== value) {
+        throw new Error(`@octoseq/mir: ${name} must be a positive integer`);
+    }
+}
+
+function mixToMono(audio: AudioBufferLike): Float32Array {
+    const nCh = audio.numberOfChannels;
+    if (nCh <= 0) {
+        throw new Error("@octoseq/mir: audio.numberOfChannels must be >= 1");
+    }
+
+    if (nCh === 1) {
+        return audio.getChannelData(0);
+    }
+
+    const length = audio.getChannelData(0).length;
+    const out = new Float32Array(length);
+
+    for (let ch = 0; ch < nCh; ch++) {
+        const data = audio.getChannelData(ch);
+        if (data.length !== length) {
+            throw new Error(
+                "@octoseq/mir: all channels must have equal length (AudioBuffer-like invariant)"
+            );
+        }
+        for (let i = 0; i < length; i++) {
+            // `out[i]` is `number|undefined` under `noUncheckedIndexedAccess`.
+            out[i] = (out[i] ?? 0) + (data[i] ?? 0);
+        }
+    }
+
+    const inv = 1 / nCh;
+    for (let i = 0; i < length; i++) out[i] = (out[i] ?? 0) * inv;
+
+    return out;
+}
+
+/**
+ * Compute a magnitude spectrogram.
+ *
+ * v0.1 implementation:
+ * - CPU STFT + FFT for correctness.
+ * - The function accepts an optional MirGPU to match the future API.
+ *   (STFT/FFT is the largest dense math block and can be ported to WebGPU later.)
+ */
+export async function spectrogram(
+    audio: AudioBufferLike,
+    config: SpectrogramConfig,
+    gpu?: MirGPU,
+    options: SpectrogramOptions = {}
+): Promise<Spectrogram> {
+    // Keep the parameter to make the expensive step explicitly reusable.
+    // (v0.1 computes FFT on CPU; GPU is accepted for future acceleration.)
+    void gpu;
+
+    assertPositiveInt("config.fftSize", config.fftSize);
+    assertPositiveInt("config.hopSize", config.hopSize);
+
+    if (config.window !== "hann") {
+        throw new Error(
+            `@octoseq/mir: unsupported window '${config.window}'. v0.1 supports only 'hann'.`
+        );
+    }
+
+    const fftSize = config.fftSize;
+    if ((fftSize & (fftSize - 1)) !== 0) {
+        throw new Error("@octoseq/mir: config.fftSize must be a power of two");
+    }
+
+    const hopSize = config.hopSize;
+    if (hopSize > fftSize) {
+        throw new Error(
+            "@octoseq/mir: config.hopSize must be <= config.fftSize"
+        );
+    }
+
+    const sr = audio.sampleRate;
+    const mono = mixToMono(audio);
+
+    // Number of frames with 'valid' windows.
+    // We prefer explicitness over padding for v0.1.
+    const nFrames = Math.max(0, 1 + Math.floor((mono.length - fftSize) / hopSize));
+
+    const times = new Float32Array(nFrames);
+    const mags: Float32Array[] = new Array(nFrames);
+
+    const window = hannWindow(fftSize);
+
+    // Reuse FFT plan and buffers across frames.
+    const fft = getFftBackend(fftSize);
+
+    // Preallocate frame buffer so we don't allocate per frame.
+    const windowedFrame = new Float32Array(fftSize);
+
+    // Minimal timing instrumentation. This is deliberately lightweight and only used
+    // for optional debug logging by callers (e.g. worker). We don't expose this in the public API.
+    let totalFftMs = 0;
+    const nowMs = (): number =>
+        typeof performance !== "undefined" ? performance.now() : Date.now();
+
+    for (let frame = 0; frame < nFrames; frame++) {
+        if (options.isCancelled?.()) {
+            throw new Error("@octoseq/mir: cancelled");
+        }
+        const start = frame * hopSize;
+
+        // time is the center of the analysis window.
+        times[frame] = (start + fftSize / 2) / sr;
+
+        // Apply windowing before FFT (same as previous implementation).
+        for (let i = 0; i < fftSize; i++) {
+            const s = mono[start + i] ?? 0;
+            windowedFrame[i] = s * (window[i] ?? 0);
+        }
+
+        const t0 = nowMs();
+        const { real, imag } = fft.forwardReal(windowedFrame);
+        totalFftMs += nowMs() - t0;
+
+        // Magnitudes: only keep the real-input half-spectrum [0..N/2] inclusive.
+        const nBins = (fftSize >>> 1) + 1;
+        const out = new Float32Array(nBins);
+        for (let k = 0; k < nBins; k++) {
+            const re = real[k] ?? 0;
+            const im = imag[k] ?? 0;
+            out[k] = Math.hypot(re, im);
+        }
+        mags[frame] = out;
+    }
+
+    // Attach as a non-enumerable debug field to avoid API changes.
+    // Consumers can optionally read it for profiling in development.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (mags as any).cpuFftTotalMs = totalFftMs;
+
+    return {
+        sampleRate: sr,
+        fftSize,
+        hopSize,
+        times,
+        magnitudes: mags
+    };
+}

package/src/gpu/README.md

@@ -0,0 +1,34 @@
+# WebGPU acceleration
+
+This folder contains the WebGPU compute implementation that powers optional GPU paths in `@octoseq/mir`.
+
+## What runs on GPU?
+
+- **Mel filterbank projection** (spectrogram magnitudes → mel bands) — real WGSL compute kernel.
+- **HPSS mask estimation** — WGSL kernels for soft harmonic/percussive masks (see `hpssMasks.wgsl.ts`).
+- FFT/STFT remains on CPU (see `src/dsp/spectrogram.ts`); GPU is used as an acceleration stage rather than a full pipeline.
+
+## Timing / observability
+
+The GPU stage measures **submit → readback completion** time (`gpuSubmitToReadbackMs`) by awaiting `GPUBuffer.mapAsync()` on a readback buffer.
+This timing is surfaced through:
+
+- `MelSpectrogram.gpuTimings.gpuSubmitToReadbackMs`
+- `MirResult.meta.timings.gpuMs` (prefers the submit→readback timing when present)
+
+## Numeric tolerance
+
+GPU and CPU results may differ slightly due to floating point order-of-operations.
+These differences should be small and not visually significant.
+A reasonable tolerance for comparison is:
+
+- `absDiff <= 1e-4` for individual mel bin values (after log10)
+- HPSS masks are soft probabilities; expect small differences in the 1e-3 range.
+
+## Files
+
+- `kernels/melProject.wgsl.ts` — WGSL kernel source
+- `kernels/hpssMasks.wgsl.ts` — WGSL kernels for harmonic/percussive mask estimation
+- `helpers.ts` — small buffer/dispatch/readback helpers
+- `melProject.ts` — kernel wrapper that runs the projection and reads back `Float32Array`
+- `hpssMasks.ts` — GPU HPSS mask orchestration + readback

package/src/gpu/context.ts

@@ -0,0 +1,44 @@
+/**
+ * WebGPU context wrapper for MIR computations.
+ *
+ * v0.1 scope:
+ * - Provide a safe, explicit way for callers to opt into GPU usage.
+ * - Throw a clear error when called outside the browser or when WebGPU is unavailable.
+ */
+export class MirGPU {
+    public readonly device: GPUDevice;
+    public readonly queue: GPUQueue;
+
+    private constructor(device: GPUDevice) {
+        this.device = device;
+        this.queue = device.queue;
+    }
+
+    static async create(): Promise<MirGPU> {
+        // Next.js note: callers must create MirGPU from a client component.
+        if (typeof navigator === "undefined") {
+            throw new Error(
+                "@octoseq/mir: WebGPU is only available in the browser (navigator is undefined)."
+            );
+        }
+
+        const nav = navigator as Navigator & { gpu?: GPU };
+        if (!nav.gpu) {
+            throw new Error(
+                "@octoseq/mir: WebGPU is unavailable (navigator.gpu is missing). Use CPU mode or a WebGPU-capable browser."
+            );
+        }
+
+        const adapter = await nav.gpu.requestAdapter();
+        if (!adapter) {
+            throw new Error(
+                "@octoseq/mir: Failed to acquire a WebGPU adapter. WebGPU may be disabled or unsupported."
+            );
+        }
+
+        // We keep this minimal: no required features for v0.1.
+        const device = await adapter.requestDevice();
+
+        return new MirGPU(device);
+    }
+}

package/src/gpu/helpers.ts

@@ -0,0 +1,87 @@
+import type { MirGPU } from "./context";
+
+export function nowMs(): number {
+    return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+
+export type GpuStageTiming = {
+    /** wall-clock time from queue.submit() to readback completion */
+    gpuSubmitToReadbackMs: number;
+};
+
+export type GpuDispatchResult<T> = {
+    value: T;
+    timing: GpuStageTiming;
+};
+
+export function byteSizeF32(n: number): number {
+    return n * 4;
+}
+
+export function createAndWriteStorageBuffer(gpu: MirGPU, data: Float32Array): GPUBuffer {
+    const buf = gpu.device.createBuffer({
+        size: byteSizeF32(data.length),
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+    // Some TS lib definitions make BufferSource incompatible with ArrayBufferLike.
+    // WebGPU implementations accept typed arrays; cast to keep this package dependency-free.
+    gpu.queue.writeBuffer(buf, 0, data as unknown as BufferSource);
+    return buf;
+}
+
+export function createUniformBufferU32x4(gpu: MirGPU, u32x4: Uint32Array): GPUBuffer {
+    if (u32x4.length !== 4) throw new Error("@octoseq/mir: uniform buffer must be 4 u32 values");
+    const buf = gpu.device.createBuffer({
+        size: 16,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+    gpu.queue.writeBuffer(buf, 0, u32x4 as unknown as BufferSource);
+    return buf;
+}
+
+export function createStorageOutBuffer(gpu: MirGPU, byteLength: number): GPUBuffer {
+    return gpu.device.createBuffer({
+        size: byteLength,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+    });
+}
+
+export function createReadbackBuffer(gpu: MirGPU, byteLength: number): GPUBuffer {
+    return gpu.device.createBuffer({
+        size: byteLength,
+        usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+    });
+}
+
+/**
+ * Submit an encoder that copies `outBuffer` to a MAP_READ buffer and returns the mapped bytes.
+ *
+ * Note: mapping is the completion signal; we intentionally measure submit->map to validate
+ * real GPU work end-to-end.
+ */
+export async function submitAndReadback(
+    gpu: MirGPU,
+    encoder: GPUCommandEncoder,
+    outBuffer: GPUBuffer,
+    readback: GPUBuffer,
+    byteLength: number
+): Promise<GpuDispatchResult<ArrayBuffer>> {
+    encoder.copyBufferToBuffer(outBuffer, 0, readback, 0, byteLength);
+
+    const tSubmit = nowMs();
+    gpu.queue.submit([encoder.finish()]);
+
+    await readback.mapAsync(GPUMapMode.READ);
+    const tDone = nowMs();
+
+    const mapped = readback.getMappedRange();
+    const copy = mapped.slice(0); // copies to standalone ArrayBuffer
+    readback.unmap();
+
+    return {
+        value: copy,
+        timing: {
+            gpuSubmitToReadbackMs: tDone - tSubmit,
+        },
+    };
+}

package/src/gpu/hpssMasks.ts

@@ -0,0 +1,116 @@
+import type { MirGPU } from "./context";
+
+import {
+    byteSizeF32,
+    createAndWriteStorageBuffer,
+    createReadbackBuffer,
+    createStorageOutBuffer,
+    createUniformBufferU32x4,
+    nowMs,
+    type GpuDispatchResult,
+} from "./helpers";
+
+import { hpssMasksWGSL } from "./kernels/hpssMasks.wgsl";
+
+export type GpuHpssMasksInput = {
+    nFrames: number;
+    nBins: number;
+    magsFlat: Float32Array; // [frame][bin] row-major, length=nFrames*nBins
+    softMask: boolean;
+};
+
+export type GpuHpssMasksOutput = {
+    harmonicMaskFlat: Float32Array; // length=nFrames*nBins
+    percussiveMaskFlat: Float32Array; // length=nFrames*nBins
+};
+
+/**
+ * Compute HPSS masks on the GPU.
+ *
+ * Notes:
+ * - This stage intentionally only estimates masks. Applying masks to the original magnitude
+ *   spectrogram is done on CPU for clarity and to preserve existing output shapes/types.
+ * - Kernel uses a fixed median-of-9 approximation (see WGSL source for details).
+ */
+export async function gpuHpssMasks(
+    gpu: MirGPU,
+    input: GpuHpssMasksInput
+): Promise<GpuDispatchResult<GpuHpssMasksOutput>> {
+    const { device } = gpu;
+
+    const { nFrames, nBins, magsFlat, softMask } = input;
+
+    if (magsFlat.length !== nFrames * nBins) {
+        throw new Error("@octoseq/mir: magsFlat length mismatch");
+    }
+
+    const magsBuffer = createAndWriteStorageBuffer(gpu, magsFlat);
+
+    const outByteLen = byteSizeF32(nFrames * nBins);
+    const harmonicOutBuffer = createStorageOutBuffer(gpu, outByteLen);
+    const percussiveOutBuffer = createStorageOutBuffer(gpu, outByteLen);
+
+    const harmonicReadback = createReadbackBuffer(gpu, outByteLen);
+    const percussiveReadback = createReadbackBuffer(gpu, outByteLen);
+
+    const shader = device.createShaderModule({ code: hpssMasksWGSL });
+    const pipeline = device.createComputePipeline({
+        layout: "auto",
+        compute: { module: shader, entryPoint: "main" },
+    });
+
+    // Params matches WGSL: (nBins, nFrames, softMaskU32, _pad)
+    const params = createUniformBufferU32x4(gpu, new Uint32Array([nBins, nFrames, softMask ? 1 : 0, 0]));
+
+    const bindGroup = device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: magsBuffer } },
+            { binding: 1, resource: { buffer: harmonicOutBuffer } },
+            { binding: 2, resource: { buffer: percussiveOutBuffer } },
+            { binding: 3, resource: { buffer: params } },
+        ],
+    });
+
+    const encoder = device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+
+    const wgX = Math.ceil(nFrames / 16);
+    const wgY = Math.ceil(nBins / 16);
+    pass.dispatchWorkgroups(wgX, wgY);
+    pass.end();
+
+    // Read back both masks from a single submission.
+    encoder.copyBufferToBuffer(harmonicOutBuffer, 0, harmonicReadback, 0, outByteLen);
+    encoder.copyBufferToBuffer(percussiveOutBuffer, 0, percussiveReadback, 0, outByteLen);
+
+    const tSubmit = nowMs();
+    gpu.queue.submit([encoder.finish()]);
+
+    await Promise.all([harmonicReadback.mapAsync(GPUMapMode.READ), percussiveReadback.mapAsync(GPUMapMode.READ)]);
+    const tDone = nowMs();
+
+    const hBytes = harmonicReadback.getMappedRange().slice(0);
+    const pBytes = percussiveReadback.getMappedRange().slice(0);
+    harmonicReadback.unmap();
+    percussiveReadback.unmap();
+
+    magsBuffer.destroy();
+    harmonicOutBuffer.destroy();
+    percussiveOutBuffer.destroy();
+    params.destroy();
+    harmonicReadback.destroy();
+    percussiveReadback.destroy();
+
+    return {
+        value: {
+            harmonicMaskFlat: new Float32Array(hBytes),
+            percussiveMaskFlat: new Float32Array(pBytes),
+        },
+        timing: {
+            gpuSubmitToReadbackMs: tDone - tSubmit,
+        },
+    };
+}

package/src/gpu/kernels/hpssMasks.wgsl.ts

@@ -0,0 +1,137 @@
+/**
+ * WGSL kernel: HPSS mask estimation (harmonic/percussive) from a linear magnitude spectrogram.
+ *
+ * CPU reference path in `src/dsp/hpss.ts` uses true median filters with configurable kernels
+ * (defaults 17x17). That is too slow, and implementing a general median on GPU would require
+ * per-pixel sorting / dynamic allocation.
+ *
+ * GPU strategy (approximation, intentionally fixed):
+ * - Use a fixed 9-tap 1D robust smoother in time (harmonic estimate) and in frequency
+ *   (percussive estimate).
+ * - Robust smoother is implemented as the exact median-of-9 via a fixed compare–swap
+ *   sorting network (no dynamic memory, no data-dependent branches, fixed cost).
+ *
+ * This yields masks that are structurally faithful for visualisation / musical use, while
+ * allowing a large performance win from GPU parallelism.
+ *
+ * Shapes:
+ * - Input mags: flattened row-major [frame][bin], length = nFrames * nBins
+ * - Output harmonicMask, percussiveMask: same layout and length
+ */
+export const hpssMasksWGSL = /* wgsl */ `
+struct Params {
+  nBins: u32,
+  nFrames: u32,
+  softMask: u32, // 1 => soft, 0 => hard
+  _pad: u32,
+};
+
+@group(0) @binding(0) var<storage, read> mags : array<f32>;
+@group(0) @binding(1) var<storage, read_write> harmonicMask : array<f32>;
+@group(0) @binding(2) var<storage, read_write> percussiveMask : array<f32>;
+@group(0) @binding(3) var<uniform> params : Params;
+
+fn clamp_i32(x: i32, lo: i32, hi: i32) -> i32 {
+  return max(lo, min(hi, x));
+}
+
+fn swap_if_greater(a: ptr<function, f32>, b: ptr<function, f32>) {
+  // Branchless compare–swap.
+  let av = *a;
+  let bv = *b;
+  *a = min(av, bv);
+  *b = max(av, bv);
+}
+
+// Sorting network for 9 values; returns the 5th smallest (median).
+//
+// Notes:
+// - This is fixed-cost and data-independent.
+// - For our HPSS approximation we only need a robust center value, and exact median-of-9
+//   is a good tradeoff vs kernel size.
+fn median9(v0: f32, v1: f32, v2: f32, v3: f32, v4: f32, v5: f32, v6: f32, v7: f32, v8: f32) -> f32 {
+  var a0 = v0; var a1 = v1; var a2 = v2;
+  var a3 = v3; var a4 = v4; var a5 = v5;
+  var a6 = v6; var a7 = v7; var a8 = v8;
+
+  // 9-input sorting network (compare–swap stages). This is a known minimal-ish network.
+  // We fully sort then take middle; cost is acceptable for 9.
+  // Stage 1
+  swap_if_greater(&a0,&a1); swap_if_greater(&a3,&a4); swap_if_greater(&a6,&a7);
+  // Stage 2
+  swap_if_greater(&a1,&a2); swap_if_greater(&a4,&a5); swap_if_greater(&a7,&a8);
+  // Stage 3
+  swap_if_greater(&a0,&a1); swap_if_greater(&a3,&a4); swap_if_greater(&a6,&a7);
+  // Stage 4
+  swap_if_greater(&a0,&a3); swap_if_greater(&a3,&a6); swap_if_greater(&a0,&a3);
+  // Stage 5
+  swap_if_greater(&a1,&a4); swap_if_greater(&a4,&a7); swap_if_greater(&a1,&a4);
+  // Stage 6
+  swap_if_greater(&a2,&a5); swap_if_greater(&a5,&a8); swap_if_greater(&a2,&a5);
+  // Stage 7
+  swap_if_greater(&a1,&a3); swap_if_greater(&a5,&a7);
+  // Stage 8
+  swap_if_greater(&a2,&a6);
+  // Stage 9
+  swap_if_greater(&a2,&a3); swap_if_greater(&a4,&a6);
+  // Stage 10
+  swap_if_greater(&a2,&a4); swap_if_greater(&a4,&a6);
+  // Stage 11
+  swap_if_greater(&a3,&a5); swap_if_greater(&a5,&a7);
+  // Stage 12
+  swap_if_greater(&a3,&a4); swap_if_greater(&a5,&a6);
+  // Stage 13
+  swap_if_greater(&a4,&a5);
+
+  return a4;
+}
+
+fn mag_at(frame: i32, bin: i32) -> f32 {
+  let f = clamp_i32(frame, 0, i32(params.nFrames) - 1);
+  let b = clamp_i32(bin, 0, i32(params.nBins) - 1);
+  let idx = u32(f) * params.nBins + u32(b);
+  return mags[idx];
+}
+
+@compute @workgroup_size(16, 16)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+  let frame = gid.x;
+  let bin = gid.y;
+
+  if (frame >= params.nFrames || bin >= params.nBins) {
+    return;
+  }
+
+  let f = i32(frame);
+  let b = i32(bin);
+
+  // Harmonic estimate: median in time over 9 taps.
+  let h = median9(
+    mag_at(f-4,b), mag_at(f-3,b), mag_at(f-2,b), mag_at(f-1,b), mag_at(f,b),
+    mag_at(f+1,b), mag_at(f+2,b), mag_at(f+3,b), mag_at(f+4,b)
+  );
+
+  // Percussive estimate: median in frequency over 9 taps.
+  let p = median9(
+    mag_at(f,b-4), mag_at(f,b-3), mag_at(f,b-2), mag_at(f,b-1), mag_at(f,b),
+    mag_at(f,b+1), mag_at(f,b+2), mag_at(f,b+3), mag_at(f,b+4)
+  );
+
+  let eps: f32 = 1e-12;
+  let denom = max(eps, h + p);
+
+  var mh = h / denom;
+  var mp = p / denom;
+
+  // Optional hard mask (kept for compatibility with CPU options).
+  if (params.softMask == 0u) {
+    let isH = h >= p;
+    mh = select(0.0, 1.0, isH);
+    mp = select(1.0, 0.0, isH);
+  }
+
+  let idx = frame * params.nBins + bin;
+  harmonicMask[idx] = mh;
+  percussiveMask[idx] = mp;
+}
+`;