@octoseq/mir 0.1.0-main.2e286ce

package/dist/index.d.ts

@@ -0,0 +1,450 @@
+export { c as Mir1DResult, d as Mir2DResult, h as MirAudioPayload, M as MirBackend, f as MirFunctionId, e as MirResult, b as MirRunMeta, g as MirRunRequest, a as MirRunTimings } from './types-BE3py4fZ.js';
+import { S as Spectrogram, M as MirGPU } from './runMir-CSIBwNZ3.js';
+export { a as SpectrogramConfig, r as runMir, s as spectrogram } from './runMir-CSIBwNZ3.js';
+
+/**
+ * Spectral centroid per frame (Hz).
+ *
+ * Output is aligned 1:1 with `spec.times`.
+ */
+declare function spectralCentroid(spec: Spectrogram): Float32Array;
+/**
+ * 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`.
+ */
+declare function spectralFlux(spec: Spectrogram): Float32Array;
+
+type MelConfig = {
+    nMels: number;
+    fMin?: number;
+    fMax?: number;
+};
+type MelSpectrogram = {
+    times: Float32Array;
+    melBands: Float32Array[];
+    /** Optional observability. Present when GPU path runs. */
+    gpuTimings?: {
+        gpuSubmitToReadbackMs: number;
+    };
+};
+/**
+ * Compute a (log) mel spectrogram by projecting an existing spectrogram.
+ *
+ * Design rule compliance:
+ * - The caller provides the spectrogram (we do not hide STFT internally).
+ * - Output is aligned to `spec.times`.
+ */
+declare function melSpectrogram(spec: Spectrogram, config: MelConfig, gpu?: MirGPU): Promise<MelSpectrogram>;
+
+type OnsetEnvelope = {
+    times: Float32Array;
+    values: Float32Array;
+};
+type OnsetEnvelopeOptions = {
+    /** If true, log-compress magnitudes/energies before differencing. */
+    useLog?: boolean;
+    /** Moving-average smoothing window length in milliseconds. 0 disables smoothing. */
+    smoothMs?: number;
+    /** How to convert temporal differences into novelty. */
+    diffMethod?: "rectified" | "abs";
+};
+declare function onsetEnvelopeFromSpectrogram(spec: Spectrogram, options?: OnsetEnvelopeOptions): OnsetEnvelope;
+declare function onsetEnvelopeFromMel(mel: MelSpectrogram, options?: OnsetEnvelopeOptions): OnsetEnvelope;
+type OnsetEnvelopeGpuResult = {
+    times: Float32Array;
+    values: Float32Array;
+    gpuTimings: {
+        gpuSubmitToReadbackMs: number;
+    };
+};
+/**
+ * GPU-accelerated onset envelope from mel spectrogram.
+ *
+ * Notes:
+ * - This bypasses JS loops for the diff+reduction step.
+ * - Smoothing/log options are intentionally limited for v0.1 (keeps WGSL simple).
+ * - Callers should fall back to CPU on errors.
+ */
+declare function onsetEnvelopeFromMelGpu(mel: MelSpectrogram, gpu: MirGPU, options?: Pick<OnsetEnvelopeOptions, "diffMethod">): Promise<OnsetEnvelopeGpuResult>;
+
+type PeakPickEvent = {
+    time: number;
+    strength: number;
+    index: number;
+};
+type PeakPickOptions = {
+    /** Minimum peak height (absolute). */
+    threshold?: number;
+    /** Minimum inter-peak interval (seconds). */
+    minIntervalSec?: number;
+    /** If provided, use adaptive threshold: mean(values) + factor*std(values). */
+    adaptive?: {
+        method?: "meanStd" | "median";
+        factor?: number;
+    };
+    /** If true, prefer strict maxima (> neighbors); else allow flat plateaus. */
+    strict?: boolean;
+};
+declare function peakPick(times: Float32Array, values: Float32Array, options?: PeakPickOptions): PeakPickEvent[];
+
+type SpectrogramLike2D = {
+    times: Float32Array;
+    bins: number;
+    frames: number;
+    magnitudes: Float32Array[];
+};
+type HpssOptions = {
+    /** Median filter kernel size along time axis (frames). Must be odd. */
+    timeMedian?: number;
+    /** Median filter kernel size along frequency axis (bins). Must be odd. */
+    freqMedian?: number;
+    /** If true, use soft masks; else hard mask. */
+    softMask?: boolean;
+    /** Cancellation hook for long loops. */
+    isCancelled?: () => boolean;
+};
+declare function hpss(spec: Spectrogram, options?: HpssOptions): {
+    harmonic: SpectrogramLike2D;
+    percussive: SpectrogramLike2D;
+};
+
+type MfccOptions = {
+    nCoeffs?: number;
+};
+type MfccResult = {
+    times: Float32Array;
+    coeffs: Float32Array[];
+};
+declare function mfcc(mel: MelSpectrogram, options?: MfccOptions): MfccResult;
+type DeltaOptions = {
+    /** Regression window size N (frames). Standard choice is 2. */
+    window?: number;
+};
+type Features2D = {
+    times: Float32Array;
+    values: Float32Array[];
+};
+declare function delta(features: Features2D, options?: DeltaOptions): Features2D;
+declare function deltaDelta(features: Features2D, options?: DeltaOptions): Features2D;
+
+type NormaliseForWaveformOptions = {
+    min?: number;
+    max?: number;
+    center?: boolean;
+};
+/**
+ * Normalise a time-aligned feature array into a waveform-friendly range.
+ *
+ * Typical uses:
+ * - Map spectralFlux or centroid to [-1, 1] to re-use a waveform renderer.
+ *
+ * Defaults:
+ * - If `center` is true: range [-1, 1] (zero-centered)
+ * - Else: range [0, 1]
+ */
+declare function normaliseForWaveform(data: Float32Array, options?: NormaliseForWaveformOptions): Float32Array;
+
+/**
+ * Display-only transforms for spectrogram-like (magnitude) data.
+ *
+ * These helpers are intentionally *not* used inside core MIR algorithms.
+ * They exist so applications can apply established visualisation practices
+ * (e.g. dB conversion, clamping) without mutating or rescaling the analysis
+ * outputs.
+ *
+ * Shape conventions:
+ * - 2D arrays are `[frame][bin]`.
+ */
+type Spectrogram2D = Float32Array[];
+type SpectrogramToDbOptions = {
+    /**
+     * Optional floor (minimum) dB value applied during conversion.
+     * This is a display convenience only.
+     */
+    floorDb?: number;
+    /** Epsilon used to avoid log(0). Defaults to 1e-12. */
+    epsilon?: number;
+};
+/**
+ * Convert linear magnitudes to dB.
+ *
+ * Formula: `db = 20 * log10(max(eps, magnitude))`
+ *
+ * Notes:
+ * - This does *not* normalise or re-reference the values.
+ * - The input is not mutated.
+ * - Intended for visualisation only.
+ */
+declare function spectrogramToDb(magnitudes2d: Spectrogram2D, options?: SpectrogramToDbOptions): Spectrogram2D;
+/**
+ * Clamp a dB-scaled 2D array to a fixed range.
+ *
+ * The input is not mutated.
+ * Intended for visualisation only.
+ */
+declare function clampDb(db2d: Spectrogram2D, minDb: number, maxDb: number): Spectrogram2D;
+
+type MinMax = {
+    min: number;
+    max: number;
+};
+/**
+ * Compute min/max in a single pass without using spread / Math.min(...arr).
+ *
+ * Safe for very large arrays (millions of samples).
+ */
+declare function minMax(values: ArrayLike<number>): MinMax;
+
+type MirFingerprintV1 = {
+    version: "v1";
+    /** Query window time bounds (seconds) – informational/debug only. */
+    t0: number;
+    t1: number;
+    mel: {
+        /** Mean mel vector across frames (weighted by frame energy, then unit-normalised). */
+        mean: Float32Array;
+        /** Variance mel vector across frames (weighted by frame energy). */
+        variance: Float32Array;
+    };
+    onset: {
+        mean: number;
+        max: number;
+        /** Peaks per second, computed using peakPick() on the onset envelope. */
+        peakDensityHz: number;
+    };
+    mfcc?: {
+        mean: Float32Array;
+        variance: Float32Array;
+    };
+};
+/**
+ * Compute a deterministic v1 fingerprint for a time region [t0, t1].
+ *
+ * Loudness independence:
+ * - Uses energy-weighted statistics. Loud frames contribute more to the shape.
+ * - Resulting mean vector is effectively the average energy distribution direction.
+ */
+declare function fingerprintV1(params: {
+    t0: number;
+    t1: number;
+    mel: MelSpectrogram;
+    onsetEnvelope: {
+        times: Float32Array;
+        values: Float32Array;
+    };
+    mfcc?: Features2D;
+    peakPick?: {
+        minIntervalSec?: number;
+        threshold?: number;
+        adaptiveFactor?: number;
+    };
+}): MirFingerprintV1;
+
+type MirFingerprintVectorWeights = {
+    /** Weight for mel(mean+variance) block. */
+    mel?: number;
+    /** Weight for transient/onset scalars block. */
+    transient?: number;
+    /** Weight for MFCC(mean+variance) block (if present). */
+    mfcc?: number;
+};
+/**
+ * Convert a v1 fingerprint into a concatenated feature vector suitable for cosine similarity.
+ *
+ * Rules:
+ * - mel and mfcc blocks are L2-normalised separately (mean+var concatenated per-block)
+ * - transient scalars are treated as a small vector and L2-normalised too
+ * - blocks are then concatenated with optional weights applied per-block
+ */
+declare function fingerprintToVectorV1(fp: MirFingerprintV1, weights?: MirFingerprintVectorWeights): Float32Array;
+declare function similarityFingerprintV1(a: MirFingerprintV1, b: MirFingerprintV1, weights?: MirFingerprintVectorWeights): number;
+
+type MirSearchCandidate = {
+    timeSec: number;
+    score: number;
+    windowStartSec: number;
+    windowEndSec: number;
+};
+type MirSearchResultV1 = {
+    times: Float32Array;
+    similarity: Float32Array;
+    candidates: MirSearchCandidate[];
+    meta: {
+        fingerprintMs: number;
+        scanMs: number;
+        totalMs: number;
+        windowSec: number;
+        hopSec: number;
+        skippedWindows: number;
+        scannedWindows: number;
+    };
+};
+type MirSearchOptionsV1 = {
+    /** Sliding window hop size in seconds. Default ~0.03s. */
+    hopSec?: number;
+    /** Similarity threshold for candidate detection. Default 0.75. */
+    threshold?: number;
+    /**
+     * Min spacing between candidates (seconds). Default is selectionDuration*0.8.
+     * Implemented via peakPick(minIntervalSec).
+     */
+    minCandidateSpacingSec?: number;
+    /** If provided, windows overlapping [skipT0, skipT1] are skipped. */
+    skipWindowOverlap?: {
+        t0: number;
+        t1: number;
+    };
+    /** Optional weights for similarity vector blocks. */
+    weights?: MirFingerprintVectorWeights;
+    /** Peak-pick settings for query fingerprint peak density. */
+    queryPeakPick?: {
+        minIntervalSec?: number;
+        threshold?: number;
+        adaptiveFactor?: number;
+    };
+    /** Peak-pick settings for candidate detection on the similarity curve. */
+    candidatePeakPick?: {
+        strict?: boolean;
+    };
+    /** Cooperative cancellation hook (called frequently in scan loop). */
+    isCancelled?: () => boolean;
+};
+declare function searchTrackV1(params: {
+    queryRegion: {
+        t0: number;
+        t1: number;
+    };
+    mel: MelSpectrogram;
+    onsetEnvelope: {
+        times: Float32Array;
+        values: Float32Array;
+    };
+    mfcc?: Features2D;
+    options?: MirSearchOptionsV1;
+}): Promise<MirSearchResultV1>;
+
+type MirRefinedModelKindV1 = "baseline" | "prototype" | "logistic";
+type MirRefinedModelExplainV1 = {
+    kind: MirRefinedModelKindV1;
+    positives: number;
+    negatives: number;
+    /** L2 norms per feature group (useful as a cheap, stable explainability hook). */
+    weightL2?: {
+        mel: number;
+        melForeground: number;
+        melContrast?: number;
+        onset: number;
+        onsetForeground: number;
+        onsetContrast?: number;
+        mfcc?: number;
+        mfccForeground?: number;
+        mfccContrast?: number;
+    };
+    /** Training diagnostics (only for logistic). */
+    training?: {
+        iterations: number;
+        finalLoss: number;
+    };
+};
+type MirLogitContributionsByGroupV1 = {
+    logit: number;
+    bias: number;
+    mel: number;
+    melForeground: number;
+    melContrast?: number;
+    onset: number;
+    onsetForeground: number;
+    onsetContrast?: number;
+    mfcc?: number;
+    mfccForeground?: number;
+    mfccContrast?: number;
+};
+
+type MirRefinementCandidateLabelV1 = {
+    t0: number;
+    t1: number;
+    status: "accepted" | "rejected";
+    source: "auto" | "manual";
+};
+type MirSearchGuidedOptionsV1 = MirSearchOptionsV1 & {
+    /**
+     * Local contrast features: foreground (query-length) vs surrounding background.
+     * Enabled by default because it improves discrimination in dense mixes.
+     */
+    localContrast?: {
+        enabled?: boolean;
+        /** Background duration multiplier relative to the foreground. Default 3. */
+        backgroundScale?: number;
+    };
+    refinement?: {
+        enabled?: boolean;
+        /**
+         * Human labels (accepted/rejected). Unreviewed candidates should not be sent.
+         */
+        labels?: MirRefinementCandidateLabelV1[];
+        /** Optional: include the query as an extra positive exemplar once enough positives exist. */
+        includeQueryAsPositive?: boolean;
+    };
+};
+type MirSearchCurveKindV1 = "similarity" | "confidence";
+type MirGuidedCandidateExplainV1 = {
+    /** Only present for logistic models; values are in logit space (sum + bias = total logit). */
+    groupLogit?: MirLogitContributionsByGroupV1;
+};
+type MirSearchCandidateV1Guided = MirSearchCandidate & {
+    explain?: MirGuidedCandidateExplainV1;
+};
+type MirSearchResultV1Guided = {
+    times: Float32Array;
+    scores: Float32Array;
+    candidates: MirSearchCandidateV1Guided[];
+    curveKind: MirSearchCurveKindV1;
+    model: MirRefinedModelExplainV1;
+    meta: {
+        /** Feature prep time (legacy name retained for UI compatibility). */
+        fingerprintMs: number;
+        scanMs: number;
+        modelMs: number;
+        totalMs: number;
+        windowSec: number;
+        hopSec: number;
+        skippedWindows: number;
+        scannedWindows: number;
+    };
+};
+declare function searchTrackV1Guided(params: {
+    queryRegion: {
+        t0: number;
+        t1: number;
+    };
+    mel: MelSpectrogram;
+    onsetEnvelope: {
+        times: Float32Array;
+        values: Float32Array;
+    };
+    mfcc?: Features2D;
+    options?: MirSearchGuidedOptionsV1;
+}): Promise<MirSearchResultV1Guided>;
+
+type MirVersion = "0.1.0";
+
+declare const MIR_VERSION: MirVersion;
+type AudioBufferLike = {
+    sampleRate: number;
+    getChannelData(channel: number): Float32Array;
+    numberOfChannels: number;
+};
+
+/**
+ * Backwards-compat placeholder from the initial skeleton.
+ *
+ * Note: kept so existing internal references/tests don't break.
+ */
+declare function helloMir(name?: string): string;
+
+export { type AudioBufferLike, type DeltaOptions, type Features2D, type HpssOptions, MIR_VERSION, type MelConfig, type MelSpectrogram, type MfccOptions, type MfccResult, type MinMax, type MirFingerprintV1, type MirFingerprintVectorWeights, MirGPU, type MirRefinementCandidateLabelV1, type MirSearchCandidate, type MirSearchCurveKindV1, type MirSearchGuidedOptionsV1, type MirSearchOptionsV1, type MirSearchResultV1, type MirSearchResultV1Guided, type MirVersion, type OnsetEnvelope, type OnsetEnvelopeGpuResult, type OnsetEnvelopeOptions, type PeakPickEvent, type PeakPickOptions, Spectrogram, type Spectrogram2D, type SpectrogramLike2D, type SpectrogramToDbOptions, clampDb, delta, deltaDelta, fingerprintToVectorV1, fingerprintV1, helloMir, hpss, melSpectrogram, mfcc, minMax, normaliseForWaveform, onsetEnvelopeFromMel, onsetEnvelopeFromMelGpu, onsetEnvelopeFromSpectrogram, peakPick, searchTrackV1, searchTrackV1Guided, similarityFingerprintV1, spectralCentroid, spectralFlux, spectrogramToDb };