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

package/src/gpu/helpers.ts

@@ -18,6 +18,15 @@ export function byteSizeF32(n: number): number {
     return n * 4;
 }
 
+/**
+ * Metadata for pooled buffers to track their properties for release.
+ */
+export interface PooledBuffer {
+    buffer: GPUBuffer;
+    size: number;
+    usage: number;
+}
+
 export function createAndWriteStorageBuffer(gpu: MirGPU, data: Float32Array): GPUBuffer {
     const buf = gpu.device.createBuffer({
         size: byteSizeF32(data.length),
@@ -85,3 +94,79 @@ export async function submitAndReadback(
         },
     };
 }
+
+// ============================================================================
+// Pooled Buffer Creation Functions
+// ============================================================================
+
+/**
+ * Create or acquire a storage buffer from the pool and write data to it.
+ *
+ * Returns a PooledBuffer that must be released back to the pool after use.
+ */
+export function createPooledStorageBuffer(gpu: MirGPU, data: Float32Array): PooledBuffer {
+    const size = byteSizeF32(data.length);
+    const usage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
+
+    const buffer = gpu.bufferPool.acquire(size, usage);
+    gpu.queue.writeBuffer(buffer, 0, data as unknown as BufferSource);
+
+    return { buffer, size, usage };
+}
+
+/**
+ * Create or acquire a uniform buffer from the pool and write u32x4 data to it.
+ *
+ * Returns a PooledBuffer that must be released back to the pool after use.
+ */
+export function createPooledUniformBufferU32x4(gpu: MirGPU, u32x4: Uint32Array): PooledBuffer {
+    if (u32x4.length !== 4) throw new Error("@octoseq/mir: uniform buffer must be 4 u32 values");
+
+    const size = 16;
+    const usage = GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST;
+
+    const buffer = gpu.bufferPool.acquire(size, usage);
+    gpu.queue.writeBuffer(buffer, 0, u32x4 as unknown as BufferSource);
+
+    return { buffer, size, usage };
+}
+
+/**
+ * Create or acquire a storage output buffer from the pool.
+ *
+ * Returns a PooledBuffer that must be released back to the pool after use.
+ */
+export function createPooledStorageOutBuffer(gpu: MirGPU, byteLength: number): PooledBuffer {
+    const usage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST;
+    const buffer = gpu.bufferPool.acquire(byteLength, usage);
+
+    return { buffer, size: byteLength, usage };
+}
+
+/**
+ * Create or acquire a readback buffer from the pool.
+ *
+ * Returns a PooledBuffer that must be released back to the pool after use.
+ */
+export function createPooledReadbackBuffer(gpu: MirGPU, byteLength: number): PooledBuffer {
+    const usage = GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST;
+    const buffer = gpu.bufferPool.acquire(byteLength, usage);
+
+    return { buffer, size: byteLength, usage };
+}
+
+/**
+ * Release a pooled buffer back to the pool for reuse.
+ */
+export function releasePooledBuffer(gpu: MirGPU, pooled: PooledBuffer): void {
+    gpu.bufferPool.release(pooled.buffer, pooled.size, pooled.usage);
+}
+
+/**
+ * Release multiple pooled buffers back to the pool at once.
+ */
+export function releasePooledBuffers(gpu: MirGPU, buffers: PooledBuffer[]): void {
+    for (const pooled of buffers) {
+        releasePooledBuffer(gpu, pooled);
+    }
+}

package/src/gpu/melProject.ts

@@ -8,6 +8,12 @@ import {
     createUniformBufferU32x4,
     submitAndReadback,
     type GpuDispatchResult,
+    createPooledStorageBuffer,
+    createPooledStorageOutBuffer,
+    createPooledUniformBufferU32x4,
+    createPooledReadbackBuffer,
+    releasePooledBuffers,
+    type PooledBuffer,
 } from "./helpers";
 
 import { melProjectWGSL } from "./kernels/melProject.wgsl";
@@ -96,3 +102,80 @@ export async function gpuMelProjectFlat(
         timing,
     };
 }
+
+/**
+ * Pooled version: Real WebGPU compute stage with buffer pooling.
+ *
+ * This version reuses buffers from the pool for better performance on repeated calls.
+ * Recommended for production use when calling frequently.
+ */
+export async function gpuMelProjectFlatPooled(
+    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");
+    }
+
+    // Acquire buffers from pool
+    const magsBuffer = createPooledStorageBuffer(gpu, magsFlat);
+    const filterBuffer = createPooledStorageBuffer(gpu, filterFlat);
+
+    const outByteLen = byteSizeF32(nFrames * nMels);
+    const outBuffer = createPooledStorageOutBuffer(gpu, outByteLen);
+    const readback = createPooledReadbackBuffer(gpu, outByteLen);
+
+    const shader = device.createShaderModule({ code: melProjectWGSL });
+    const pipeline = device.createComputePipeline({
+        layout: "auto",
+        compute: {
+            module: shader,
+            entryPoint: "main",
+        },
+    });
+
+    const params = createPooledUniformBufferU32x4(gpu, new Uint32Array([nBins, nMels, nFrames, 0]));
+
+    const bindGroup = device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: magsBuffer.buffer } },
+            { binding: 1, resource: { buffer: filterBuffer.buffer } },
+            { binding: 2, resource: { buffer: outBuffer.buffer } },
+            { binding: 3, resource: { buffer: params.buffer } },
+        ],
+    });
+
+    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.buffer,
+        readback.buffer,
+        outByteLen
+    );
+
+    // Release buffers back to pool (no destroy!)
+    releasePooledBuffers(gpu, [magsBuffer, filterBuffer, outBuffer, params, readback]);
+
+    const outFlat = new Float32Array(bytes);
+    return {
+        value: { outFlat },
+        timing,
+    };
+}

package/src/index.ts

@@ -6,10 +6,55 @@ export type {
   MirRunMeta,
   Mir1DResult,
   Mir2DResult,
+  MirActivityDiagnostics,
+  MirActivityResult,
   MirResult,
   MirFunctionId,
   MirRunRequest,
-  MirAudioPayload
+  MirAudioPayload,
+  BeatCandidate,
+  BeatCandidateSource,
+  BeatCandidatesResult,
+  TempoHypothesis,
+  TempoHypothesisEvidence,
+  TempoHypothesesResult,
+  BeatGrid,
+  PhaseHypothesis,
+  PhaseAlignmentConfig,
+  // Musical Time (B4)
+  MusicalTimeProvenance,
+  MusicalTimeSegment,
+  MusicalTimeStructure,
+  BeatPosition,
+  // Frequency Bands (F1)
+  FrequencyBandTimeScope,
+  FrequencySegment,
+  FrequencyBandProvenance,
+  FrequencyBand,
+  FrequencyBandStructure,
+  FrequencyBoundsAtTime,
+  // Frequency Bands (F2)
+  FrequencyKeyframe,
+  // Band-Scoped MIR (F3)
+  BandMirFunctionId,
+  BandCqtFunctionId,
+  BandEventFunctionId,
+  BandMirDiagnostics,
+  BandMir1DResult,
+  BandCqt1DResult,
+  BandMirEvent,
+  BandEventDiagnostics,
+  BandEventsResult,
+  // CQT (F5)
+  CqtConfig,
+  CqtSpectrogram,
+  CqtSignalId,
+  CqtSignalResult,
+  // Band Proposals (F5)
+  BandProposalSource,
+  BandProposal,
+  BandProposalConfig,
+  BandProposalResult,
 } from "./types";
 
 export const MIR_VERSION: MirVersion = "0.1.0";
@@ -47,18 +92,207 @@ export { spectrogram } from "./dsp/spectrogram";
 // Derived spectral features (CPU, reuse spectrogram)
 // ----------------------------
 
-export { spectralCentroid, spectralFlux } from "./dsp/spectral";
+export type { AmplitudeEnvelopeConfig, AmplitudeEnvelopeResult } from "./dsp/spectral";
+export { amplitudeEnvelope, spectralCentroid, spectralFlux } from "./dsp/spectral";
 
 // ----------------------------
 // Onsets / Peaks
 // ----------------------------
 
-export type { OnsetEnvelope, OnsetEnvelopeOptions, OnsetEnvelopeGpuResult } from "./dsp/onset";
+export type {
+    OnsetEnvelope,
+    OnsetEnvelopeResult,
+    OnsetDiagnostics,
+    OnsetEnvelopeOptions,
+    OnsetEnvelopeGpuResult,
+    SilenceGateConfig,
+    BinGateConfig,
+    SilenceGateResult,
+} from "./dsp/onset";
 export { onsetEnvelopeFromSpectrogram, onsetEnvelopeFromMel, onsetEnvelopeFromMelGpu } from "./dsp/onset";
 
+export {
+    computeFrameEnergyFromMel,
+    computeFrameEnergyFromSpectrogram,
+    computeSilenceGating,
+    estimateNoiseFloor,
+    buildActivityMask,
+    withSilenceGateDefaults,
+    withBinGateDefaults,
+} from "./dsp/silenceGating";
+
+// ----------------------------
+// Activity Signal
+// ----------------------------
+
+export type {
+    ActivitySignal,
+    ActivityConfig,
+    ActivityDiagnostics,
+} from "./dsp/activity";
+export {
+    computeActivityFromMel,
+    computeActivityFromSpectrogram,
+    computeActivityFromAudio,
+    applyActivityGating,
+    interpolateActivity,
+} from "./dsp/activity";
+
 export type { PeakPickEvent, PeakPickOptions } from "./dsp/peakPick";
 export { peakPick } from "./dsp/peakPick";
 
+// ----------------------------
+// Beat Candidates
+// ----------------------------
+
+export type { BeatCandidatesOptions, BeatCandidatesOutput, BeatSalienceSignal } from "./dsp/beatCandidates";
+export { detectBeatCandidates, beatSalienceFromMel } from "./dsp/beatCandidates";
+
+// ----------------------------
+// Tempo Hypotheses
+// ----------------------------
+
+export type { TempoHypothesesOptions, TempoHypothesesOutput } from "./dsp/tempoHypotheses";
+export { generateTempoHypotheses } from "./dsp/tempoHypotheses";
+
+// ----------------------------
+// Phase Alignment (Beat Grid)
+// ----------------------------
+
+export { computePhaseHypotheses, generateBeatTimes } from "./dsp/phaseAlignment";
+
+// ----------------------------
+// Peak Picking
+// ----------------------------
+
+export {
+    pickPeaks,
+    pickPeaksAdaptive,
+    computeAdaptiveThreshold,
+    applyHysteresisGate,
+    DEFAULT_PEAK_PICKING_PARAMS,
+    type PeakPickingParams,
+    type PeakPickingResult,
+    type AdaptivePeakPickingResult,
+    type HysteresisGateParams,
+} from "./dsp/peakPicking";
+
+// ----------------------------
+// Musical Time (B4)
+// ----------------------------
+
+export {
+    findSegmentAtTime,
+    computeBeatPosition,
+    computeBeatPositionFromStructure,
+    generateSegmentId,
+    createSegmentFromGrid,
+    createMusicalTimeStructure,
+    validateSegments,
+    sortSegments,
+    splitSegment,
+    generateSegmentBeatTimes,
+} from "./dsp/musicalTime";
+
+// ----------------------------
+// Frequency Bands (F1)
+// ----------------------------
+
+export {
+    // ID generation
+    generateBandId,
+    // Validation
+    validateFrequencySegments,
+    validateFrequencyBand,
+    validateBandStructure,
+    // Creation
+    createBandStructure,
+    createConstantBand,
+    createSectionedBand,
+    createStandardBands,
+    // Queries
+    bandsActiveAt,
+    frequencyBoundsAt,
+    allFrequencyBoundsAt,
+    findBandById,
+    // Sorting
+    sortBands,
+    sortFrequencySegments,
+    // Modification
+    touchStructure,
+    addBandToStructure,
+    removeBandFromStructure,
+    updateBandInStructure,
+    // Keyframe Helpers (F2)
+    keyframesFromBand,
+    segmentsFromKeyframes,
+    splitBandSegmentAt,
+    mergeAdjacentSegments,
+    removeKeyframe,
+    updateKeyframe,
+    moveKeyframeTime,
+} from "./dsp/frequencyBand";
+
+// ----------------------------
+// Band-Scoped MIR (F3)
+// ----------------------------
+
+export type { BandMaskOptions, MaskedSpectrogram } from "./dsp/bandMask";
+export {
+    binToHz,
+    hzToBin,
+    computeBandMaskAtTime,
+    applyBandMaskToSpectrogram,
+    computeFrameEnergy,
+    computeFrameAmplitude,
+} from "./dsp/bandMask";
+
+export type { BandMirOptions, BandMirBatchRequest, BandMirBatchResult } from "./dsp/bandMir";
+export {
+    bandAmplitudeEnvelope,
+    bandOnsetStrength,
+    bandSpectralFlux,
+    bandSpectralCentroid,
+    runBandMirBatch,
+    getBandMirFunctionLabel,
+} from "./dsp/bandMir";
+
+// ----------------------------
+// Band Events (F3)
+// ----------------------------
+
+export type {
+    BandOnsetPeaksOptions,
+    BandBeatCandidatesOptions,
+    BandEventsBatchRequest,
+    BandEventsBatchResult,
+} from "./dsp/bandEvents";
+export {
+    bandOnsetPeaks,
+    bandBeatCandidates,
+    runBandEventsBatch,
+    getBandEventFunctionLabel,
+} from "./dsp/bandEvents";
+
+// ----------------------------
+// Band CQT (F3)
+// ----------------------------
+
+export type {
+    BandCqtOptions,
+    MaskedCqtSpectrogram,
+    BandCqtBatchRequest,
+    BandCqtBatchResult,
+} from "./dsp/bandCqt";
+export {
+    applyBandMaskToCqt,
+    bandCqtHarmonicEnergy,
+    bandCqtBassPitchMotion,
+    bandCqtTonalStability,
+    runBandCqtBatch,
+    getBandCqtFunctionLabel,
+} from "./dsp/bandCqt";
+
 // ----------------------------
 // HPSS
 // ----------------------------
@@ -77,8 +311,129 @@ export { mfcc, delta, deltaDelta } from "./dsp/mfcc";
 // Mel spectrogram
 // ----------------------------
 
-export type { MelConfig, MelSpectrogram } from "./dsp/mel";
-export { melSpectrogram } from "./dsp/mel";
+export type { MelConfig, MelSpectrogram, MelConversionConfig } from "./dsp/mel";
+export { melSpectrogram, hzToMel, melToHz, hzToFeatureIndex, featureIndexToHz } from "./dsp/mel";
+
+// ----------------------------
+// CQT (F5)
+// ----------------------------
+
+export type { CqtOptions } from "./dsp/cqt";
+export {
+    cqtSpectrogram,
+    computeCqt,
+    cqtBinToHz,
+    hzToCqtBin,
+    getNumOctaves,
+    getNumBins,
+    getCqtBinFrequencies,
+    withCqtDefaults,
+    CQT_DEFAULTS,
+} from "./dsp/cqt";
+
+export {
+    harmonicEnergy,
+    bassPitchMotion,
+    tonalStability,
+    computeCqtSignal,
+    computeAllCqtSignals,
+} from "./dsp/cqtSignals";
+
+// ----------------------------
+// Pitch Detection (P1)
+// ----------------------------
+
+export type { PitchConfig, PitchResult, PitchActivityOptions } from "./dsp/pitch";
+export { pitchF0, pitchConfidence } from "./dsp/pitch";
+
+// ----------------------------
+// Band Proposals (F5)
+// ----------------------------
+
+export type { BandProposalOptions } from "./dsp/bandProposal";
+export { generateBandProposals } from "./dsp/bandProposal";
+
+// ----------------------------
+// Custom Signal Reduction
+// ----------------------------
+
+export type {
+    ReductionInput,
+    ReductionAlgorithmId,
+    BinRangeOptions,
+    OnsetStrengthOptions,
+    SpectralFluxOptions,
+    ReductionOptions,
+    ReductionResult,
+    // Polarity
+    PolarityMode,
+    // Stabilization
+    StabilizationMode,
+    EnvelopeMode,
+    StabilizationOptions,
+} from "./dsp/customSignalReduction";
+export {
+    reduce2DToSignal,
+    getReductionAlgorithmLabel,
+    getReductionAlgorithmDescription,
+    // Polarity
+    applyPolarity,
+    // Stabilization
+    stabilizeSignal,
+    // Statistics
+    computePercentiles,
+    computeLocalStats,
+} from "./dsp/customSignalReduction";
+
+// ----------------------------
+// Event to Signal Conversion
+// ----------------------------
+
+export type {
+    DiscreteEvent,
+    EventWindowSpec,
+    EnvelopeShape,
+    EventToSignalOptions,
+    EventSignalResult,
+    EventReducer,
+    EventToSignalParams,
+} from "./dsp/eventToSignal";
+export {
+    eventCount,
+    eventDensity,
+    weightedSum,
+    weightedMean,
+    eventEnvelope,
+    eventsToSignal,
+} from "./dsp/eventToSignal";
+
+// ----------------------------
+// Signal Transforms
+// ----------------------------
+
+export type {
+    TransformSmoothMovingAverage,
+    TransformSmoothExponential,
+    TransformSmoothGaussian,
+    TransformSmooth,
+    TransformNormalizeMinMax,
+    TransformNormalizeRobust,
+    TransformNormalizeZScore,
+    TransformNormalize,
+    TransformScale,
+    TransformPolarity,
+    TransformClamp,
+    TransformRemap,
+    TransformStep,
+    TransformChain,
+    TransformContext,
+} from "./dsp/signalTransforms";
+export {
+    applyTransformStep,
+    applyTransformChain,
+    getTransformLabel,
+    createDefaultTransform,
+} from "./dsp/signalTransforms";
 
 // ----------------------------
 // Visualisation utilities
@@ -88,6 +443,12 @@ export { normaliseForWaveform } from "./util/normalise";
 export type { Spectrogram2D, SpectrogramToDbOptions } from "./util/display";
 export { spectrogramToDb, clampDb } from "./util/display";
 
+// ----------------------------
+// Audio Preprocessing
+// ----------------------------
+
+export { resample } from "./dsp/resample";
+
 // ----------------------------
 // Utility helpers
 // ----------------------------