@octoseq/mir 0.1.0-main.2e286ce → 0.1.0-main.4baa7cd

package/dist/{runMir-CSIBwNZ3.d.ts → runMir-CVEIxPd3.d.ts}

@@ -1,4 +1,4 @@
-import { h as MirAudioPayload, g as MirRunRequest, e as MirResult } from './types-BE3py4fZ.js';
+import { h as MirAudioPayload, g as MirRunRequest, e as MirResult } from './types-4bAZI4F7.js';
 
 /**
  * WebGPU context wrapper for MIR computations.

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-CVEIxPd3.js';
+import '../types-4bAZI4F7.js';

package/dist/runner/runMir.js

@@ -1,3 +1,3 @@
-export { runMir } from '../chunk-DUWYCAVG.js';
+export { runMir } from '../chunk-KIGWMJLC.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 { g as MirRunRequest, e as MirResult, B as BeatCandidate, T as TempoHypothesis, h as MirAudioPayload } from '../types-4bAZI4F7.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"]}

package/dist/types-4bAZI4F7.d.ts

@@ -0,0 +1,190 @@
+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;
+};
+/**
+ * A beat candidate represents a plausible beat-like moment in the audio.
+ *
+ * These are sparse events (timestamps) that may or may not correspond to
+ * actual beats. They are not tempo-aligned and do not imply any BPM value.
+ *
+ * Beat candidates are intended to be:
+ * - Dense enough to include most true beats
+ * - Sparse enough to be computationally tractable
+ * - Inspectable in the UI for debugging
+ *
+ * Future milestones will cluster, align, and refine these candidates.
+ */
+type BeatCandidate = {
+    /** Time in seconds from track start. */
+    time: number;
+    /** Relative salience/confidence (0-1 normalized). Higher = more likely to be a beat. */
+    strength: number;
+    /** Source of this candidate (for debugging/inspection). */
+    source: BeatCandidateSource;
+};
+type BeatCandidateSource = "onset_peak" | "flux_peak" | "combined";
+type BeatCandidatesResult = {
+    kind: "beatCandidates";
+    /** Frame times from the underlying analysis (for alignment). */
+    times: Float32Array;
+    /** The beat candidate events. */
+    candidates: BeatCandidate[];
+    /** Optional: the salience signal used for peak picking (for debugging). */
+    salience?: {
+        times: Float32Array;
+        values: Float32Array;
+    };
+    meta: MirRunMeta;
+};
+/**
+ * A tempo hypothesis represents a plausible BPM with confidence score.
+ *
+ * Hypotheses are derived from inter-onset intervals of beat candidates.
+ * They are grouped into harmonic families (e.g., 60, 120, 180 BPM) but
+ * not collapsed - each BPM is preserved as a separate hypothesis.
+ */
+type TempoHypothesis = {
+    /** Deterministic identifier for this hypothesis (e.g., "hyp-0"). */
+    id: string;
+    /** Tempo in beats per minute (0.1 BPM precision). */
+    bpm: number;
+    /** Confidence score normalized to [0, 1]. Higher = more likely. */
+    confidence: number;
+    /** Evidence metadata for debugging/inspection. */
+    evidence: TempoHypothesisEvidence;
+    /** Harmonic family ID - hypotheses in the same family are harmonically related. */
+    familyId: string;
+    /** Harmonic relationship to the family root (1.0 = root, 2.0 = double, 0.5 = half, etc.). */
+    harmonicRatio: number;
+};
+type TempoHypothesisEvidence = {
+    /** Number of IOIs supporting this tempo. */
+    supportingIntervalCount: number;
+    /** Sum of weighted contributions (if strength-weighting enabled). */
+    weightedSupport: number;
+    /** Peak height in the histogram. */
+    peakHeight: number;
+    /** Histogram bin range [minBpm, maxBpm]. */
+    binRange: [number, number];
+};
+type TempoHypothesesResult = {
+    kind: "tempoHypotheses";
+    /** Frame times from underlying analysis (for alignment). */
+    times: Float32Array;
+    /** Ordered list of tempo hypotheses (by confidence descending). */
+    hypotheses: TempoHypothesis[];
+    /** The number of beat candidates used as input. */
+    inputCandidateCount: number;
+    /** Histogram data for debugging/visualization. */
+    histogram?: {
+        bpmBins: Float32Array;
+        counts: Float32Array;
+    };
+    meta: MirRunMeta;
+};
+type MirResult = Mir1DResult | Mir2DResult | MirEventsResult | BeatCandidatesResult | TempoHypothesesResult;
+type MirFunctionId = "spectralCentroid" | "spectralFlux" | "melSpectrogram" | "onsetEnvelope" | "onsetPeaks" | "beatCandidates" | "tempoHypotheses" | "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";
+        };
+    };
+    beatCandidates?: {
+        /** Minimum inter-candidate interval in seconds. Default: 0.1 (100ms). */
+        minIntervalSec?: number;
+        /** Threshold factor for peak detection. Lower = more candidates. Default: 0.5. */
+        thresholdFactor?: number;
+        /** Smoothing window for salience signal in ms. Default: 50. */
+        smoothMs?: number;
+        /** Whether to include the salience signal in output (for debugging). */
+        includeSalience?: boolean;
+    };
+    tempoHypotheses?: {
+        /** Minimum BPM to consider. Default: 24. */
+        minBpm?: number;
+        /** Maximum BPM to consider. Default: 300. */
+        maxBpm?: number;
+        /** Histogram bin size in BPM. Default: 1.0. */
+        binSizeBpm?: number;
+        /** Maximum number of hypotheses to return. Default: 10. */
+        maxHypotheses?: number;
+        /** Minimum confidence threshold (0-1). Default: 0.05. */
+        minConfidence?: number;
+        /** Weight IOIs by beat candidate strength. Default: true. */
+        weightByStrength?: boolean;
+        /** Include histogram in output for debugging. Default: false. */
+        includeHistogram?: boolean;
+    };
+};
+type MirAudioPayload = {
+    sampleRate: number;
+    mono: Float32Array;
+};
+
+export type { BeatCandidate as B, MirBackend as M, TempoHypothesis as T, MirRunTimings as a, MirRunMeta as b, Mir1DResult as c, Mir2DResult as d, MirResult as e, MirFunctionId as f, MirRunRequest as g, MirAudioPayload as h, BeatCandidateSource as i, BeatCandidatesResult as j, TempoHypothesisEvidence as k, TempoHypothesesResult as l };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@octoseq/mir",
-    "version": "0.1.0-main.2e286ce",
+    "version": "0.1.0-main.4baa7cd",
     "description": "WebGPU-accelerated Music Information Retrieval (MIR) library (skeleton)",
     "license": "MIT",
     "private": false,

package/src/dsp/beatCandidates.ts

@@ -0,0 +1,299 @@
+import type { MelSpectrogram } from "./mel";
+import type { OnsetEnvelope } from "./onset";
+import { onsetEnvelopeFromMel } from "./onset";
+import type { Spectrogram } from "./spectrogram";
+import { spectralFlux } from "./spectral";
+import type { BeatCandidate, BeatCandidateSource } from "../types";
+
+/**
+ * Configuration for beat candidate detection.
+ */
+export type BeatCandidatesOptions = {
+    /** Minimum inter-candidate interval in seconds. Default: 0.1 (100ms). */
+    minIntervalSec?: number;
+    /** Threshold factor for adaptive peak detection. Lower = more candidates. Default: 0.5. */
+    thresholdFactor?: number;
+    /** Smoothing window for salience signal in ms. Default: 50. */
+    smoothMs?: number;
+};
+
+/**
+ * Result of beat candidate detection.
+ */
+export type BeatCandidatesOutput = {
+    candidates: BeatCandidate[];
+    /** The computed salience signal (for debugging/visualization). */
+    salience: {
+        times: Float32Array;
+        values: Float32Array;
+    };
+};
+
+/**
+ * Compute a beat-oriented salience signal from mel spectrogram.
+ *
+ * This combines:
+ * - Onset envelope (captures transients/attacks)
+ * - Spectral flux from the underlying spectrogram (captures spectral change)
+ *
+ * The signals are normalized and combined to produce a single salience curve
+ * suitable for peak picking.
+ *
+ * Key design choices:
+ * - Whole-track normalization (z-score) for consistent behavior
+ * - Gentle smoothing to suppress micro-transients while preserving beat structure
+ * - No BPM inference or grid assumptions
+ */
+export type BeatSalienceSignal = {
+    times: Float32Array;
+    values: Float32Array;
+};
+
+function movingAverage(values: Float32Array, windowFrames: number): Float32Array {
+    if (windowFrames <= 1) return values;
+
+    const n = values.length;
+    const out = new Float32Array(n);
+
+    const half = Math.floor(windowFrames / 2);
+
+    // Prefix sums for O(n) moving average.
+    const prefix = new Float64Array(n + 1);
+    prefix[0] = 0;
+    for (let i = 0; i < n; i++) {
+        prefix[i + 1] = (prefix[i] ?? 0) + (values[i] ?? 0);
+    }
+
+    for (let i = 0; i < n; i++) {
+        const start = Math.max(0, i - half);
+        const end = Math.min(n, i + half + 1);
+        const sum = (prefix[end] ?? 0) - (prefix[start] ?? 0);
+        const count = Math.max(1, end - start);
+        out[i] = sum / count;
+    }
+
+    return out;
+}
+
+function meanStd(values: Float32Array): { mean: number; std: number } {
+    const n = values.length;
+    if (n <= 0) return { mean: 0, std: 0 };
+
+    let mean = 0;
+    for (let i = 0; i < n; i++) mean += values[i] ?? 0;
+    mean /= n;
+
+    let varSum = 0;
+    for (let i = 0; i < n; i++) {
+        const d = (values[i] ?? 0) - mean;
+        varSum += d * d;
+    }
+
+    const std = Math.sqrt(varSum / n);
+    return { mean, std };
+}
+
+/**
+ * Z-score normalize a signal (whole-track normalization).
+ * Result has mean ~0 and std ~1.
+ */
+function zScoreNormalize(values: Float32Array): Float32Array {
+    const { mean, std } = meanStd(values);
+    const n = values.length;
+    const out = new Float32Array(n);
+
+    if (std === 0 || !Number.isFinite(std)) {
+        // Degenerate case: all values are the same
+        out.fill(0);
+        return out;
+    }
+
+    for (let i = 0; i < n; i++) {
+        out[i] = ((values[i] ?? 0) - mean) / std;
+    }
+
+    return out;
+}
+
+/**
+ * Min-max normalize to [0, 1] range.
+ */
+function minMaxNormalize(values: Float32Array): Float32Array {
+    const n = values.length;
+    if (n === 0) return new Float32Array(0);
+
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < n; i++) {
+        const v = values[i] ?? 0;
+        if (v < min) min = v;
+        if (v > max) max = v;
+    }
+
+    const out = new Float32Array(n);
+    const range = max - min;
+
+    if (range === 0 || !Number.isFinite(range)) {
+        out.fill(0.5);
+        return out;
+    }
+
+    for (let i = 0; i < n; i++) {
+        out[i] = ((values[i] ?? 0) - min) / range;
+    }
+
+    return out;
+}
+
+/**
+ * Compute beat salience signal from mel spectrogram.
+ *
+ * This is an intermediate signal suitable for peak picking to extract
+ * beat candidates. It combines onset envelope with additional smoothing
+ * tuned for beat-like (rather than onset-like) detection.
+ */
+export function beatSalienceFromMel(
+    mel: MelSpectrogram,
+    spec: Spectrogram,
+    options?: { smoothMs?: number }
+): BeatSalienceSignal {
+    const smoothMs = options?.smoothMs ?? 50;
+
+    // Compute onset envelope with more smoothing than default onset detection.
+    // We want to capture the "attack envelope" of beats, not individual onsets.
+    const onset = onsetEnvelopeFromMel(mel, {
+        smoothMs: smoothMs,
+        diffMethod: "rectified",
+        useLog: false,
+    });
+
+    // Compute spectral flux from the spectrogram.
+    const flux = spectralFlux(spec);
+
+    // Ensure times align (they should, but be defensive).
+    const n = Math.min(onset.times.length, flux.length);
+
+    // Z-score normalize both signals for equal contribution.
+    const onsetNorm = zScoreNormalize(onset.values.subarray(0, n));
+    const fluxNorm = zScoreNormalize(flux.subarray(0, n));
+
+    // Combine: weighted sum favoring onset envelope (it's more beat-specific).
+    const combined = new Float32Array(n);
+    const onsetWeight = 0.7;
+    const fluxWeight = 0.3;
+
+    for (let i = 0; i < n; i++) {
+        combined[i] = onsetWeight * (onsetNorm[i] ?? 0) + fluxWeight * (fluxNorm[i] ?? 0);
+    }
+
+    // Apply final smoothing to reduce micro-peaks.
+    const dt = n >= 2 ? ((onset.times[1] ?? 0) - (onset.times[0] ?? 0)) : 0.01;
+    const windowFrames = Math.max(1, Math.round((smoothMs / 1000) / Math.max(1e-9, dt)));
+    const smoothed = movingAverage(combined, windowFrames | 1);
+
+    // Normalize to [0, 1] for consistent interpretation.
+    const normalized = minMaxNormalize(smoothed);
+
+    return {
+        times: onset.times.subarray(0, n),
+        values: normalized,
+    };
+}
+
+/**
+ * Pick peaks from the salience signal to extract beat candidates.
+ *
+ * Uses relaxed parameters to err on the side of too many candidates.
+ * The goal is coverage, not precision.
+ */
+function pickBeatCandidates(
+    salience: BeatSalienceSignal,
+    options: BeatCandidatesOptions,
+    source: BeatCandidateSource
+): BeatCandidate[] {
+    const minIntervalSec = options.minIntervalSec ?? 0.1;
+    const thresholdFactor = options.thresholdFactor ?? 0.5;
+
+    const { times, values } = salience;
+    const n = values.length;
+
+    if (n < 3) return [];
+
+    // Compute adaptive threshold based on signal statistics.
+    const { mean, std } = meanStd(values);
+    // Low threshold to get dense candidates.
+    // thresholdFactor of 0.5 means: mean + 0.5*std (quite low).
+    const threshold = mean + thresholdFactor * std;
+
+    const candidates: BeatCandidate[] = [];
+    let lastPeakTime = -Infinity;
+
+    for (let i = 1; i < n - 1; i++) {
+        const v = values[i] ?? 0;
+
+        // Must be above threshold.
+        if (v < threshold) continue;
+
+        // Must be a local maximum.
+        const prev = values[i - 1] ?? 0;
+        const next = values[i + 1] ?? 0;
+        if (!(v > prev && v > next)) continue;
+
+        const t = times[i] ?? 0;
+
+        // Enforce minimum interval.
+        if (t - lastPeakTime < minIntervalSec) {
+            // If within interval, keep the stronger peak.
+            const last = candidates[candidates.length - 1];
+            if (last && v > last.strength) {
+                last.time = t;
+                last.strength = v;
+            }
+            continue;
+        }
+
+        candidates.push({
+            time: t,
+            strength: v,
+            source,
+        });
+        lastPeakTime = t;
+    }
+
+    return candidates;
+}
+
+/**
+ * Detect beat candidates from mel spectrogram and spectrogram.
+ *
+ * This is the main entry point for beat candidate detection.
+ *
+ * Design principles:
+ * - Dense candidates (err on side of too many)
+ * - No BPM inference
+ * - No grid assumptions
+ * - Whole-track normalization for consistency
+ * - Deterministic (same input -> same output)
+ */
+export function detectBeatCandidates(
+    mel: MelSpectrogram,
+    spec: Spectrogram,
+    options?: BeatCandidatesOptions
+): BeatCandidatesOutput {
+    const opts: BeatCandidatesOptions = {
+        minIntervalSec: options?.minIntervalSec ?? 0.1,
+        thresholdFactor: options?.thresholdFactor ?? 0.5,
+        smoothMs: options?.smoothMs ?? 50,
+    };
+
+    // Compute beat salience signal.
+    const salience = beatSalienceFromMel(mel, spec, { smoothMs: opts.smoothMs });
+
+    // Pick peaks from salience.
+    const candidates = pickBeatCandidates(salience, opts, "combined");
+
+    return {
+        candidates,
+        salience,
+    };
+}