@octoseq/mir 0.1.0-main.0d2814e

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

@@ -0,0 +1,48 @@
+/**
+ * WGSL kernel: mel filterbank projection.
+ *
+ * Computes per-frame mel band energies:
+ *   out[frame, mel] = log10(eps + sum_k mags[frame, k] * filters[mel, k])
+ *
+ * Notes:
+ * - FFT/STFT stays on CPU (spectrogram()). This kernel only accelerates the dense projection.
+ * - Numerical differences vs CPU are expected to be small (floating point order-of-ops).
+ */
+export const melProjectWGSL = /* wgsl */ `
+struct Params {
+  nBins: u32,
+  nMels: u32,
+  nFrames: u32,
+  _pad: u32,
+};
+
+@group(0) @binding(0) var<storage, read> mags : array<f32>;
+@group(0) @binding(1) var<storage, read> filters : array<f32>;
+@group(0) @binding(2) var<storage, read_write> out : array<f32>;
+@group(0) @binding(3) var<uniform> params : Params;
+
+fn log10(x: f32) -> f32 {
+  return log(x) / log(10.0);
+}
+
+@compute @workgroup_size(16, 16)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+  let frame = gid.x;
+  let mel = gid.y;
+  if (frame >= params.nFrames || mel >= params.nMels) {
+    return;
+  }
+
+  var sum: f32 = 0.0;
+  let bins = params.nBins;
+  let magBase = frame * bins;
+  let filBase = mel * bins;
+
+  for (var k: u32 = 0u; k < bins; k = k + 1u) {
+    sum = sum + mags[magBase + k] * filters[filBase + k];
+  }
+
+  let eps: f32 = 1e-12;
+  out[frame * params.nMels + mel] = log10(eps + sum);
+}
+`;

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

@@ -0,0 +1,56 @@
+export const onsetEnvelopeWGSL = /* wgsl */ `
+// Compute onset strength envelope from a (log) mel spectrogram.
+//
+// Input layout: melFlat[t*nMels + m]
+// Output layout: out[t]
+//
+// We compute novelty per frame:
+//   novelty[t] = sum_m max(0, mel[t,m] - mel[t-1,m])   (rectified)
+//            or sum_m abs(...)
+//
+// One invocation computes one frame index (t). This is memory-bound but reduces a full
+// (frames*mels) loop to the GPU and provides an end-to-end submit->readback timing.
+
+struct Params {
+  nMels: u32,
+  nFrames: u32,
+  diffMethod: u32, // 0=rectified, 1=abs
+  _pad: u32,
+};
+
+@group(0) @binding(0) var<storage, read> melFlat: array<f32>;
+@group(0) @binding(1) var<storage, read_write> out: array<f32>;
+@group(0) @binding(2) var<uniform> params: Params;
+
+@compute @workgroup_size(256)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let t = gid.x;
+  if (t >= params.nFrames) { return; }
+
+  if (t == 0u) {
+    out[t] = 0.0;
+    return;
+  }
+
+  let nMels = params.nMels;
+  var sum: f32 = 0.0;
+
+  // Linear loop: nMels is small (e.g. 64). Keeping it serial per-frame is fine.
+  // (Future optimisation: parallelise reduction within workgroup.)
+  for (var m: u32 = 0u; m < nMels; m = m + 1u) {
+    let a = melFlat[t * nMels + m];
+    let b = melFlat[(t - 1u) * nMels + m];
+    let d = a - b;
+
+    if (params.diffMethod == 1u) {
+      // abs
+      sum = sum + abs(d);
+    } else {
+      // rectified
+      sum = sum + max(0.0, d);
+    }
+  }
+
+  out[t] = sum / max(1.0, f32(nMels));
+}
+`;

package/src/gpu/melProject.ts

@@ -0,0 +1,98 @@
+import type { MirGPU } from "./context";
+
+import {
+    byteSizeF32,
+    createAndWriteStorageBuffer,
+    createReadbackBuffer,
+    createStorageOutBuffer,
+    createUniformBufferU32x4,
+    submitAndReadback,
+    type GpuDispatchResult,
+} from "./helpers";
+
+import { melProjectWGSL } from "./kernels/melProject.wgsl";
+
+export type GpuMelProjectInput = {
+    nFrames: number;
+    nBins: number;
+    nMels: number;
+    magsFlat: Float32Array; // length = nFrames*nBins
+    filterFlat: Float32Array; // length = nMels*nBins
+};
+
+export type GpuMelProjectOutput = {
+    outFlat: Float32Array; // length = nFrames*nMels
+};
+
+/**
+ * Real WebGPU compute stage: dense mel projection.
+ *
+ * Returns outFlat plus GPU timing that measures submit->readback.
+ */
+export async function gpuMelProjectFlat(
+    gpu: MirGPU,
+    input: GpuMelProjectInput
+): Promise<GpuDispatchResult<GpuMelProjectOutput>> {
+    const { device } = gpu;
+
+    const { nFrames, nBins, nMels, magsFlat, filterFlat } = input;
+    if (magsFlat.length !== nFrames * nBins) {
+        throw new Error("@octoseq/mir: magsFlat length mismatch");
+    }
+    if (filterFlat.length !== nMels * nBins) {
+        throw new Error("@octoseq/mir: filterFlat length mismatch");
+    }
+
+    const magsBuffer = createAndWriteStorageBuffer(gpu, magsFlat);
+    const filterBuffer = createAndWriteStorageBuffer(gpu, filterFlat);
+
+    const outByteLen = byteSizeF32(nFrames * nMels);
+    const outBuffer = createStorageOutBuffer(gpu, outByteLen);
+    const readback = createReadbackBuffer(gpu, outByteLen);
+
+    const shader = device.createShaderModule({ code: melProjectWGSL });
+    const pipeline = device.createComputePipeline({
+        layout: "auto",
+        compute: {
+            module: shader,
+            entryPoint: "main",
+        },
+    });
+
+    const params = createUniformBufferU32x4(gpu, new Uint32Array([nBins, nMels, nFrames, 0]));
+
+    const bindGroup = device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: magsBuffer } },
+            { binding: 1, resource: { buffer: filterBuffer } },
+            { binding: 2, resource: { buffer: outBuffer } },
+            { 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(nMels / 16);
+    pass.dispatchWorkgroups(wgX, wgY);
+    pass.end();
+
+    const { value: bytes, timing } = await submitAndReadback(gpu, encoder, outBuffer, readback, outByteLen);
+
+    // Cleanup (simple; no pooling in v0.1)
+    magsBuffer.destroy();
+    filterBuffer.destroy();
+    outBuffer.destroy();
+    params.destroy();
+    readback.destroy();
+
+    const outFlat = new Float32Array(bytes);
+    return {
+        value: { outFlat },
+        timing,
+    };
+}

package/src/gpu/onsetEnvelope.ts

@@ -0,0 +1,81 @@
+import type { MirGPU } from "./context";
+
+import {
+    byteSizeF32,
+    createAndWriteStorageBuffer,
+    createReadbackBuffer,
+    createStorageOutBuffer,
+    createUniformBufferU32x4,
+    submitAndReadback,
+    type GpuDispatchResult,
+} from "./helpers";
+
+import { onsetEnvelopeWGSL } from "./kernels/onsetEnvelope.wgsl";
+
+export type GpuOnsetEnvelopeInput = {
+    nFrames: number;
+    nMels: number;
+    melFlat: Float32Array; // length=nFrames*nMels
+    diffMethod: "rectified" | "abs";
+};
+
+export type GpuOnsetEnvelopeOutput = {
+    out: Float32Array; // length=nFrames
+};
+
+export async function gpuOnsetEnvelopeFromMelFlat(
+    gpu: MirGPU,
+    input: GpuOnsetEnvelopeInput
+): Promise<GpuDispatchResult<GpuOnsetEnvelopeOutput>> {
+    const { device } = gpu;
+
+    const { nFrames, nMels, melFlat, diffMethod } = input;
+    if (melFlat.length !== nFrames * nMels) {
+        throw new Error("@octoseq/mir: melFlat length mismatch");
+    }
+
+    const melBuffer = createAndWriteStorageBuffer(gpu, melFlat);
+
+    const outByteLen = byteSizeF32(nFrames);
+    const outBuffer = createStorageOutBuffer(gpu, outByteLen);
+    const readback = createReadbackBuffer(gpu, outByteLen);
+
+    const shader = device.createShaderModule({ code: onsetEnvelopeWGSL });
+    const pipeline = device.createComputePipeline({
+        layout: "auto",
+        compute: { module: shader, entryPoint: "main" },
+    });
+
+    const diffU32 = diffMethod === "abs" ? 1 : 0;
+    const params = createUniformBufferU32x4(gpu, new Uint32Array([nMels, nFrames, diffU32, 0]));
+
+    const bindGroup = device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: melBuffer } },
+            { binding: 1, resource: { buffer: outBuffer } },
+            { binding: 2, resource: { buffer: params } },
+        ],
+    });
+
+    const encoder = device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+
+    const wg = Math.ceil(nFrames / 256);
+    pass.dispatchWorkgroups(wg);
+    pass.end();
+
+    const { value: bytes, timing } = await submitAndReadback(gpu, encoder, outBuffer, readback, outByteLen);
+
+    melBuffer.destroy();
+    outBuffer.destroy();
+    params.destroy();
+    readback.destroy();
+
+    return {
+        value: { out: new Float32Array(bytes) },
+        timing,
+    };
+}

package/src/gpu/webgpu.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Minimal WebGPU type declarations.
+ *
+ * Why this exists:
+ * - TypeScript's built-in lib set does not always include WebGPU types in all environments.
+ * - We avoid adding extra dependencies in this scaffold package.
+ *
+ * These declarations are intentionally minimal and are designed to *merge* with real WebGPU
+ * types when they are available (interface merging), rather than conflicting.
+ */
+
+export { };
+
+declare global {
+    interface Navigator {
+        gpu?: GPU;
+    }
+
+    interface GPU {
+        requestAdapter(options?: GPURequestAdapterOptions): Promise<GPUAdapter | null>;
+    }
+
+    interface GPURequestAdapterOptions {
+        powerPreference?: "low-power" | "high-performance";
+        forceFallbackAdapter?: boolean;
+    }
+
+    interface GPUAdapter {
+        requestDevice(descriptor?: GPUDeviceDescriptor): Promise<GPUDevice>;
+    }
+
+    interface GPUDeviceDescriptor {
+        requiredFeatures?: Iterable<string>;
+        requiredLimits?: Record<string, number>;
+        label?: string;
+    }
+
+    interface GPUDevice {
+        readonly queue: GPUQueue;
+        createBuffer(descriptor: GPUBufferDescriptor): GPUBuffer;
+        createShaderModule(descriptor: GPUShaderModuleDescriptor): GPUShaderModule;
+        createComputePipeline(descriptor: GPUComputePipelineDescriptor): GPUComputePipeline;
+        createBindGroupLayout(descriptor: GPUBindGroupLayoutDescriptor): GPUBindGroupLayout;
+        createPipelineLayout(descriptor: GPUPipelineLayoutDescriptor): GPUPipelineLayout;
+        createBindGroup(descriptor: GPUBindGroupDescriptor): GPUBindGroup;
+        createCommandEncoder(descriptor?: GPUCommandEncoderDescriptor): GPUCommandEncoder;
+    }
+
+    interface GPUQueue {
+        writeBuffer(
+            buffer: GPUBuffer,
+            bufferOffset: number,
+            data: BufferSource,
+            dataOffset?: number,
+            size?: number
+        ): void;
+        submit(commandBuffers: Iterable<GPUCommandBuffer>): void;
+    }
+
+    interface GPUBuffer {
+        mapAsync(mode: number, offset?: number, size?: number): Promise<void>;
+        getMappedRange(offset?: number, size?: number): ArrayBuffer;
+        unmap(): void;
+        destroy(): void;
+    }
+
+    interface GPUBufferDescriptor {
+        size: number;
+        usage: number;
+        mappedAtCreation?: boolean;
+        label?: string;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    interface GPUShaderModule { }
+
+    interface GPUShaderModuleDescriptor {
+        code: string;
+        label?: string;
+    }
+
+    interface GPUComputePipeline {
+        getBindGroupLayout(index: number): GPUBindGroupLayout;
+    }
+
+    interface GPUComputePipelineDescriptor {
+        layout?: GPUPipelineLayout | "auto";
+        compute: {
+            module: GPUShaderModule;
+            entryPoint: string;
+        };
+        label?: string;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    interface GPUBindGroupLayout { }
+
+    interface GPUBindGroupLayoutDescriptor {
+        entries: Array<{
+            binding: number;
+            visibility: number;
+            buffer?: { type?: "uniform" | "storage" | "read-only-storage" };
+        }>;
+        label?: string;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    interface GPUPipelineLayout { }
+
+    interface GPUPipelineLayoutDescriptor {
+        bindGroupLayouts: GPUBindGroupLayout[];
+        label?: string;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    interface GPUBindGroup { }
+
+    interface GPUBindGroupDescriptor {
+        layout: GPUBindGroupLayout;
+        entries: Array<{ binding: number; resource: { buffer: GPUBuffer } }>;
+        label?: string;
+    }
+
+    interface GPUCommandEncoder {
+        beginComputePass(descriptor?: GPUComputePassDescriptor): GPUComputePassEncoder;
+        copyBufferToBuffer(
+            source: GPUBuffer,
+            sourceOffset: number,
+            destination: GPUBuffer,
+            destinationOffset: number,
+            size: number
+        ): void;
+        finish(): GPUCommandBuffer;
+    }
+
+    interface GPUCommandEncoderDescriptor {
+        label?: string;
+    }
+
+    interface GPUComputePassEncoder {
+        setPipeline(pipeline: GPUComputePipeline): void;
+        setBindGroup(index: number, bindGroup: GPUBindGroup): void;
+        dispatchWorkgroups(
+            workgroupCountX: number,
+            workgroupCountY?: number,
+            workgroupCountZ?: number
+        ): void;
+        end(): void;
+    }
+
+    interface GPUComputePassDescriptor {
+        label?: string;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    interface GPUCommandBuffer { }
+
+    // Common WebGPU constants. These are numbers in the real API.
+    // We declare them as `var` so they exist at runtime only if provided by the environment.
+    // (We only use these constants when running in a WebGPU-capable browser.)
+    var GPUBufferUsage: {
+        MAP_READ: number;
+        COPY_DST: number;
+        COPY_SRC: number;
+        STORAGE: number;
+        UNIFORM: number;
+    };
+
+    var GPUMapMode: {
+        READ: number;
+    };
+
+    var GPUShaderStage: {
+        COMPUTE: number;
+    };
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+export type MirVersion = "0.1.0";
+
+export type {
+  MirBackend,
+  MirRunTimings,
+  MirRunMeta,
+  Mir1DResult,
+  Mir2DResult,
+  MirResult,
+  MirFunctionId,
+  MirRunRequest,
+  MirAudioPayload
+} from "./types";
+
+export const MIR_VERSION: MirVersion = "0.1.0";
+
+// ----------------------------
+// Core Types
+// ----------------------------
+
+export type AudioBufferLike = {
+  sampleRate: number;
+  getChannelData(channel: number): Float32Array;
+  numberOfChannels: number;
+};
+
+// ----------------------------
+// GPU
+// ----------------------------
+
+export { MirGPU } from "./gpu/context";
+
+// ----------------------------
+// Shared runner (main thread / worker)
+// ----------------------------
+
+export { runMir } from "./runner/runMir";
+
+// ----------------------------
+// Spectrogram (shared primitive)
+// ----------------------------
+
+export type { SpectrogramConfig, Spectrogram } from "./dsp/spectrogram";
+export { spectrogram } from "./dsp/spectrogram";
+
+// ----------------------------
+// Derived spectral features (CPU, reuse spectrogram)
+// ----------------------------
+
+export { spectralCentroid, spectralFlux } from "./dsp/spectral";
+
+// ----------------------------
+// Onsets / Peaks
+// ----------------------------
+
+export type { OnsetEnvelope, OnsetEnvelopeOptions, OnsetEnvelopeGpuResult } from "./dsp/onset";
+export { onsetEnvelopeFromSpectrogram, onsetEnvelopeFromMel, onsetEnvelopeFromMelGpu } from "./dsp/onset";
+
+export type { PeakPickEvent, PeakPickOptions } from "./dsp/peakPick";
+export { peakPick } from "./dsp/peakPick";
+
+// ----------------------------
+// HPSS
+// ----------------------------
+
+export type { SpectrogramLike2D, HpssOptions } from "./dsp/hpss";
+export { hpss } from "./dsp/hpss";
+
+// ----------------------------
+// MFCC + Deltas
+// ----------------------------
+
+export type { MfccOptions, MfccResult, DeltaOptions, Features2D } from "./dsp/mfcc";
+export { mfcc, delta, deltaDelta } from "./dsp/mfcc";
+
+// ----------------------------
+// Mel spectrogram
+// ----------------------------
+
+export type { MelConfig, MelSpectrogram } from "./dsp/mel";
+export { melSpectrogram } from "./dsp/mel";
+
+// ----------------------------
+// Visualisation utilities
+// ----------------------------
+
+export { normaliseForWaveform } from "./util/normalise";
+export type { Spectrogram2D, SpectrogramToDbOptions } from "./util/display";
+export { spectrogramToDb, clampDb } from "./util/display";
+
+// ----------------------------
+// Utility helpers
+// ----------------------------
+
+export type { MinMax } from "./util/stats";
+export { minMax } from "./util/stats";
+
+// ----------------------------
+// Search (deterministic within-track similarity)
+// ----------------------------
+
+export type { MirFingerprintV1 } from "./search/fingerprintV1";
+export { fingerprintV1 } from "./search/fingerprintV1";
+
+export type { MirFingerprintVectorWeights } from "./search/similarity";
+export { fingerprintToVectorV1, similarityFingerprintV1 } from "./search/similarity";
+
+export type { MirSearchCandidate, MirSearchOptionsV1, MirSearchResultV1 } from "./search/searchTrackV1";
+export { searchTrackV1 } from "./search/searchTrackV1";
+
+export type { MirRefinementCandidateLabelV1, MirSearchCurveKindV1, MirSearchGuidedOptionsV1, MirSearchResultV1Guided } from "./search/searchTrackV1Guided";
+export { searchTrackV1Guided } from "./search/searchTrackV1Guided";
+
+/**
+ * Backwards-compat placeholder from the initial skeleton.
+ *
+ * Note: kept so existing internal references/tests don't break.
+ */
+export function helloMir(name = "world") {
+  return `Hello, ${name} from @octoseq/mir v${MIR_VERSION}`;
+}