@octoseq/mir 0.1.0-main.4ecb074 → 0.1.0-main.5fdb072

package/dist/runMir-CnJQbBr8.d.ts

@@ -0,0 +1,187 @@
+import { G as MirAudioPayload, E as MirRunRequest, A as MirResult } from './types-DqH4umN8.js';
+
+interface BufferPoolStats {
+    totalBuffers: number;
+    activeBuffers: number;
+    availableBuffers: number;
+    poolsByUsage: Map<number, number>;
+    totalMemoryBytes: number;
+}
+/**
+ * Buffer pool configuration options.
+ */
+interface BufferPoolOptions {
+    /**
+     * Maximum number of buffers to keep in the pool per usage type.
+     * Default: 32
+     */
+    maxBuffersPerUsage?: number;
+    /**
+     * Time in milliseconds before an unused buffer is destroyed.
+     * Default: 60000 (1 minute)
+     */
+    bufferTTLMs?: number;
+    /**
+     * Whether to enable automatic cleanup of old buffers.
+     * Default: true
+     */
+    enableAutoCleanup?: boolean;
+    /**
+     * Interval in milliseconds for automatic cleanup.
+     * Default: 30000 (30 seconds)
+     */
+    cleanupIntervalMs?: number;
+}
+/**
+ * BufferPool manages reusable GPU buffers to reduce allocation overhead.
+ *
+ * Usage:
+ * ```ts
+ * const pool = new BufferPool(gpu.device);
+ * const buffer = pool.acquire(1024, GPUBufferUsage.STORAGE);
+ * // ... use buffer ...
+ * pool.release(buffer);
+ * ```
+ */
+declare class BufferPool {
+    private device;
+    private options;
+    private availableBuffers;
+    private activeBuffers;
+    private cleanupInterval;
+    constructor(device: GPUDevice, options?: BufferPoolOptions);
+    /**
+     * Acquire a buffer from the pool or create a new one if none available.
+     *
+     * @param size - Byte size of the buffer
+     * @param usage - Buffer usage flags (e.g. GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST)
+     * @returns A GPUBuffer ready for use
+     */
+    acquire(size: number, usage: number): GPUBuffer;
+    /**
+     * Release a buffer back to the pool for reuse.
+     *
+     * @param buffer - The buffer to release
+     * @param size - Original size of the buffer
+     * @param usage - Original usage flags of the buffer
+     */
+    release(buffer: GPUBuffer, size: number, usage: number): void;
+    /**
+     * Clean up old unused buffers that exceed the TTL.
+     */
+    cleanup(): void;
+    /**
+     * Destroy all pooled buffers and clear the pool.
+     */
+    clear(): void;
+    /**
+     * Get statistics about the buffer pool.
+     */
+    getStats(): BufferPoolStats;
+    /**
+     * Start automatic cleanup of old buffers.
+     */
+    private startAutoCleanup;
+    /**
+     * Stop automatic cleanup.
+     */
+    stopAutoCleanup(): void;
+    /**
+     * Dispose of the buffer pool and destroy all buffers.
+     */
+    dispose(): void;
+}
+
+/**
+ * WebGPU context wrapper for MIR computations.
+ *
+ * Includes buffer pooling for efficient GPU memory reuse across operations.
+ */
+declare class MirGPU {
+    readonly device: GPUDevice;
+    readonly queue: GPUQueue;
+    readonly bufferPool: BufferPool;
+    private constructor();
+    static create(bufferPoolOptions?: BufferPoolOptions): Promise<MirGPU>;
+    /**
+     * Get statistics about buffer pool usage.
+     */
+    getBufferPoolStats(): BufferPoolStats;
+    /**
+     * Manually trigger buffer pool cleanup (normally runs automatically).
+     */
+    cleanupBufferPool(): void;
+    /**
+     * Dispose of the GPU context and clean up all resources.
+     */
+    dispose(): void;
+}
+
+type AudioBufferLike = {
+    sampleRate: number;
+    getChannelData(channel: number): Float32Array;
+    numberOfChannels: number;
+};
+type SpectrogramConfig = {
+    fftSize: number;
+    hopSize: number;
+    window: "hann";
+};
+type SpectrogramOptions = {
+    /** Optional cancellation hook; checked once per frame. */
+    isCancelled?: () => boolean;
+};
+type Spectrogram = {
+    sampleRate: number;
+    fftSize: number;
+    hopSize: number;
+    times: Float32Array;
+    magnitudes: Float32Array[];
+};
+/**
+ * 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.)
+ */
+declare function spectrogram(audio: AudioBufferLike, config: SpectrogramConfig, gpu?: MirGPU, options?: SpectrogramOptions): Promise<Spectrogram>;
+
+type RunMirOptions = {
+    gpu?: MirGPU;
+    /** If provided, long loops should periodically call this and abort if true. */
+    isCancelled?: () => boolean;
+    /** If true and backend==='gpu', do not silently fall back to CPU on GPU errors. */
+    strictGpu?: boolean;
+    onset?: {
+        smoothMs?: number;
+        diffMethod?: "rectified" | "abs";
+        useLog?: boolean;
+    };
+    peakPick?: {
+        minIntervalSec?: number;
+        threshold?: number;
+        adaptiveFactor?: number;
+    };
+    hpss?: {
+        timeMedian?: number;
+        freqMedian?: number;
+        spectrogram?: SpectrogramConfig;
+    };
+    mfcc?: {
+        nCoeffs?: number;
+        spectrogram?: SpectrogramConfig;
+    };
+};
+type RunMirBackendOptions = RunMirOptions;
+/**
+ * Shared MIR execution entrypoint used by the main thread and by the worker.
+ *
+ * Notes:
+ * - We keep FFT/STFT on CPU for now (spectrogram()), but allow one downstream stage
+ *   (mel projection) to run on real WebGPU via `melSpectrogram(spec, config, gpu)`.
+ */
+declare function runMir(audio: MirAudioPayload, request: MirRunRequest, options?: RunMirOptions): Promise<MirResult>;
+
+export { type AudioBufferLike as A, MirGPU as M, type RunMirOptions as R, type Spectrogram as S, type SpectrogramConfig as a, type RunMirBackendOptions as b, runMir as r, spectrogram as s };

package/dist/runner/runMir.d.ts

@@ -1,2 +1,2 @@
-export { b as RunMirBackendOptions, R as RunMirOptions, r as runMir } from '../runMir-CSIBwNZ3.js';
-import '../types-BE3py4fZ.js';
+export { b as RunMirBackendOptions, R as RunMirOptions, r as runMir } from '../runMir-CnJQbBr8.js';
+import '../types-DqH4umN8.js';

package/dist/runner/runMir.js

@@ -1,3 +1,3 @@
-export { runMir } from '../chunk-DUWYCAVG.js';
+export { runMir } from '../chunk-HF3QHCRK.js';
 //# sourceMappingURL=runMir.js.map
 //# sourceMappingURL=runMir.js.map

package/dist/runner/workerProtocol.d.ts

@@ -1,4 +1,4 @@
-import { g as MirRunRequest, e as MirResult, h as MirAudioPayload } from '../types-BE3py4fZ.js';
+import { E as MirRunRequest, A as MirResult, B as BeatCandidate, T as TempoHypothesis, G as MirAudioPayload } from '../types-DqH4umN8.js';
 
 type MirWorkerInitMessage = {
     type: "INIT";
@@ -85,6 +85,13 @@ type MirWorkerResultMessage = {
             strength: number;
             index: number;
         }>;
+        candidates?: BeatCandidate[];
+        hypotheses?: TempoHypothesis[];
+        inputCandidateCount?: number;
+        histogram?: {
+            bpmBins: ArrayBufferLike;
+            counts: ArrayBufferLike;
+        };
         meta: MirResult["meta"];
     };
 };

package/dist/runner/workerProtocol.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/runner/workerProtocol.ts"],"names":[],"mappings":";AAuLO,SAAS,oBAAoB,CAAA,EAAkD;AAClF,EAAA,OAAO;AAAA,IACH,YAAY,CAAA,CAAE,UAAA;AAAA,IACd,IAAA,EAAM,IAAI,YAAA,CAAa,CAAA,CAAE,IAAmB;AAAA,GAChD;AACJ","file":"workerProtocol.js","sourcesContent":["import type { MirAudioPayload, MirResult, MirRunRequest } from \"../types\";\n\nexport type MirWorkerInitMessage = {\n    type: \"INIT\";\n    enableGpu: boolean;\n};\n\nexport type MirWorkerRunMessage = {\n    type: \"RUN\";\n    jobId: string;\n    request: MirRunRequest;\n    audio: {\n        sampleRate: number;\n        mono: ArrayBufferLike; // transferred\n    };\n    enableGpu: boolean;\n    strictGpu?: boolean;\n};\n\nexport type MirWorkerCancelMessage = {\n    type: \"CANCEL\";\n    jobId: string;\n};\n\nexport type MirWorkerSearchMessage = {\n    type: \"SEARCH\";\n    jobId: string;\n\n    audio: {\n        sampleRate: number;\n        mono: ArrayBufferLike; // transferred\n    };\n\n    query: {\n        t0: number;\n        t1: number;\n    };\n\n    /** Search tuning (kept small and explicit, like MirRunRequest). */\n    search?: {\n        hopSec?: number;\n        threshold?: number;\n        /** 0..1; if true, skip windows overlapping the query itself. */\n        skipOverlap?: boolean;\n        weights?: {\n            mel?: number;\n            transient?: number;\n            mfcc?: number;\n        };\n        /** Optional: apply softmax to similarity curve before returning. */\n        applySoftmax?: boolean;\n    };\n\n    /** Feature extraction config (re-uses existing MIR request knobs). */\n    features?: {\n        spectrogram?: MirRunRequest[\"spectrogram\"];\n        mel?: MirRunRequest[\"mel\"];\n        onset?: MirRunRequest[\"onset\"];\n        mfcc?: MirRunRequest[\"mfcc\"];\n    };\n\n    /**\n     * Optional human-in-the-loop refinement data.\n     * When enabled, the worker can use accepted/rejected exemplars to produce a\n     * per-track confidence curve and a re-ranked candidate list.\n     */\n    refinement?: {\n        enabled?: boolean;\n        includeQueryAsPositive?: boolean;\n        labels?: Array<{\n            t0: number;\n            t1: number;\n            status: \"accepted\" | \"rejected\";\n            source: \"auto\" | \"manual\";\n        }>;\n    };\n\n    enableGpu: boolean;\n    strictGpu?: boolean;\n};\n\nexport type MirWorkerInMessage = MirWorkerInitMessage | MirWorkerRunMessage | MirWorkerSearchMessage | MirWorkerCancelMessage;\n\nexport type MirWorkerResultMessage = {\n    type: \"RESULT\";\n    jobId: string;\n    /** Total time spent in the worker handling this RUN, including (optional) GPU readback. */\n    workerTotalMs: number;\n    result: {\n        // Mirror MirResult but transfer underlying buffers.\n        kind: MirResult[\"kind\"];\n        times: ArrayBufferLike;\n        values?: ArrayBufferLike;\n        data2d?: ArrayBufferLike[];\n        events?: Array<{ time: number; strength: number; index: number }>;\n        meta: MirResult[\"meta\"];\n    };\n};\n\nexport type MirWorkerErrorMessage = {\n    type: \"ERROR\";\n    jobId: string;\n    message: string;\n    stack?: string;\n};\n\nexport type MirWorkerLogMessage = {\n    type: \"LOG\";\n    jobId?: string;\n    level: \"debug\" | \"info\" | \"warn\" | \"error\";\n    message: string;\n    data?: unknown;\n};\n\nexport type MirWorkerSearchResultMessage = {\n    type: \"SEARCH_RESULT\";\n    jobId: string;\n    timings: {\n        fingerprintMs: number;\n        scanMs: number;\n        modelMs?: number;\n        totalMs: number;\n    };\n    result: {\n        times: ArrayBufferLike;\n        scores: ArrayBufferLike;\n        curveKind: \"similarity\" | \"confidence\";\n        model: {\n            kind: \"baseline\" | \"prototype\" | \"logistic\";\n            positives: number;\n            negatives: number;\n            weightL2?: {\n                mel: number;\n                melForeground: number;\n                melContrast?: number;\n                onset: number;\n                onsetForeground: number;\n                onsetContrast?: number;\n                mfcc?: number;\n                mfccForeground?: number;\n                mfccContrast?: number;\n            };\n            training?: {\n                iterations: number;\n                finalLoss: number;\n            };\n        };\n        candidates: Array<{\n            timeSec: number;\n            score: number;\n            windowStartSec: number;\n            windowEndSec: number;\n            explain?: {\n                groupLogit?: {\n                    logit: number;\n                    bias: number;\n                    mel: number;\n                    melForeground: number;\n                    melContrast?: number;\n                    onset: number;\n                    onsetForeground: number;\n                    onsetContrast?: number;\n                    mfcc?: number;\n                    mfccForeground?: number;\n                    mfccContrast?: number;\n                };\n            };\n        }>;\n        meta: {\n            windowSec: number;\n            hopSec: number;\n            skippedWindows: number;\n            scannedWindows: number;\n        };\n    };\n};\n\nexport type MirWorkerOutMessage =\n    | MirWorkerResultMessage\n    | MirWorkerSearchResultMessage\n    | MirWorkerErrorMessage\n    | MirWorkerLogMessage;\n\nexport function rebuildAudioPayload(a: MirWorkerRunMessage[\"audio\"]): MirAudioPayload {\n    return {\n        sampleRate: a.sampleRate,\n        mono: new Float32Array(a.mono as ArrayBuffer),\n    };\n}\n"]}
+{"version":3,"sources":["../../src/runner/workerProtocol.ts"],"names":[],"mappings":";AA+LO,SAAS,oBAAoB,CAAA,EAAkD;AAClF,EAAA,OAAO;AAAA,IACH,YAAY,CAAA,CAAE,UAAA;AAAA,IACd,IAAA,EAAM,IAAI,YAAA,CAAa,CAAA,CAAE,IAAmB;AAAA,GAChD;AACJ","file":"workerProtocol.js","sourcesContent":["import type { BeatCandidate, MirAudioPayload, MirResult, MirRunRequest, TempoHypothesis } from \"../types\";\n\nexport type MirWorkerInitMessage = {\n    type: \"INIT\";\n    enableGpu: boolean;\n};\n\nexport type MirWorkerRunMessage = {\n    type: \"RUN\";\n    jobId: string;\n    request: MirRunRequest;\n    audio: {\n        sampleRate: number;\n        mono: ArrayBufferLike; // transferred\n    };\n    enableGpu: boolean;\n    strictGpu?: boolean;\n};\n\nexport type MirWorkerCancelMessage = {\n    type: \"CANCEL\";\n    jobId: string;\n};\n\nexport type MirWorkerSearchMessage = {\n    type: \"SEARCH\";\n    jobId: string;\n\n    audio: {\n        sampleRate: number;\n        mono: ArrayBufferLike; // transferred\n    };\n\n    query: {\n        t0: number;\n        t1: number;\n    };\n\n    /** Search tuning (kept small and explicit, like MirRunRequest). */\n    search?: {\n        hopSec?: number;\n        threshold?: number;\n        /** 0..1; if true, skip windows overlapping the query itself. */\n        skipOverlap?: boolean;\n        weights?: {\n            mel?: number;\n            transient?: number;\n            mfcc?: number;\n        };\n        /** Optional: apply softmax to similarity curve before returning. */\n        applySoftmax?: boolean;\n    };\n\n    /** Feature extraction config (re-uses existing MIR request knobs). */\n    features?: {\n        spectrogram?: MirRunRequest[\"spectrogram\"];\n        mel?: MirRunRequest[\"mel\"];\n        onset?: MirRunRequest[\"onset\"];\n        mfcc?: MirRunRequest[\"mfcc\"];\n    };\n\n    /**\n     * Optional human-in-the-loop refinement data.\n     * When enabled, the worker can use accepted/rejected exemplars to produce a\n     * per-track confidence curve and a re-ranked candidate list.\n     */\n    refinement?: {\n        enabled?: boolean;\n        includeQueryAsPositive?: boolean;\n        labels?: Array<{\n            t0: number;\n            t1: number;\n            status: \"accepted\" | \"rejected\";\n            source: \"auto\" | \"manual\";\n        }>;\n    };\n\n    enableGpu: boolean;\n    strictGpu?: boolean;\n};\n\nexport type MirWorkerInMessage = MirWorkerInitMessage | MirWorkerRunMessage | MirWorkerSearchMessage | MirWorkerCancelMessage;\n\nexport type MirWorkerResultMessage = {\n    type: \"RESULT\";\n    jobId: string;\n    /** Total time spent in the worker handling this RUN, including (optional) GPU readback. */\n    workerTotalMs: number;\n    result: {\n        // Mirror MirResult but transfer underlying buffers.\n        kind: MirResult[\"kind\"];\n        times: ArrayBufferLike;\n        values?: ArrayBufferLike;\n        data2d?: ArrayBufferLike[];\n        events?: Array<{ time: number; strength: number; index: number }>;\n        candidates?: BeatCandidate[];\n        // For tempoHypotheses\n        hypotheses?: TempoHypothesis[];\n        inputCandidateCount?: number;\n        histogram?: {\n            bpmBins: ArrayBufferLike;\n            counts: ArrayBufferLike;\n        };\n        meta: MirResult[\"meta\"];\n    };\n};\n\nexport type MirWorkerErrorMessage = {\n    type: \"ERROR\";\n    jobId: string;\n    message: string;\n    stack?: string;\n};\n\nexport type MirWorkerLogMessage = {\n    type: \"LOG\";\n    jobId?: string;\n    level: \"debug\" | \"info\" | \"warn\" | \"error\";\n    message: string;\n    data?: unknown;\n};\n\nexport type MirWorkerSearchResultMessage = {\n    type: \"SEARCH_RESULT\";\n    jobId: string;\n    timings: {\n        fingerprintMs: number;\n        scanMs: number;\n        modelMs?: number;\n        totalMs: number;\n    };\n    result: {\n        times: ArrayBufferLike;\n        scores: ArrayBufferLike;\n        curveKind: \"similarity\" | \"confidence\";\n        model: {\n            kind: \"baseline\" | \"prototype\" | \"logistic\";\n            positives: number;\n            negatives: number;\n            weightL2?: {\n                mel: number;\n                melForeground: number;\n                melContrast?: number;\n                onset: number;\n                onsetForeground: number;\n                onsetContrast?: number;\n                mfcc?: number;\n                mfccForeground?: number;\n                mfccContrast?: number;\n            };\n            training?: {\n                iterations: number;\n                finalLoss: number;\n            };\n        };\n        candidates: Array<{\n            timeSec: number;\n            score: number;\n            windowStartSec: number;\n            windowEndSec: number;\n            explain?: {\n                groupLogit?: {\n                    logit: number;\n                    bias: number;\n                    mel: number;\n                    melForeground: number;\n                    melContrast?: number;\n                    onset: number;\n                    onsetForeground: number;\n                    onsetContrast?: number;\n                    mfcc?: number;\n                    mfccForeground?: number;\n                    mfccContrast?: number;\n                };\n            };\n        }>;\n        meta: {\n            windowSec: number;\n            hopSec: number;\n            skippedWindows: number;\n            scannedWindows: number;\n        };\n    };\n};\n\nexport type MirWorkerOutMessage =\n    | MirWorkerResultMessage\n    | MirWorkerSearchResultMessage\n    | MirWorkerErrorMessage\n    | MirWorkerLogMessage;\n\nexport function rebuildAudioPayload(a: MirWorkerRunMessage[\"audio\"]): MirAudioPayload {\n    return {\n        sampleRate: a.sampleRate,\n        mono: new Float32Array(a.mono as ArrayBuffer),\n    };\n}\n"]}