@octoseq/mir 0.1.0-main.2e286ce

package/src/search/similarity.ts

@@ -0,0 +1,98 @@
+import type { MirFingerprintV1 } from "./fingerprintV1";
+
+export 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;
+};
+
+function l2Norm(v: Float32Array): number {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) {
+        const x = v[i] ?? 0;
+        sum += x * x;
+    }
+    return Math.sqrt(sum);
+}
+
+function normaliseL2InPlace(v: Float32Array, eps = 1e-12): void {
+    const n = l2Norm(v);
+    const d = n > eps ? n : 1;
+    for (let i = 0; i < v.length; i++) v[i] = (v[i] ?? 0) / d;
+}
+
+function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+    if (a.length !== b.length) throw new Error("@octoseq/mir: cosineSimilarity length mismatch");
+    let dot = 0;
+    let aa = 0;
+    let bb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        dot += x * y;
+        aa += x * x;
+        bb += y * y;
+    }
+    const denom = Math.sqrt(aa) * Math.sqrt(bb);
+    if (denom <= 0) return 0;
+
+    // Map cosine [-1,1] -> [0,1]. With our features it tends to be >= 0 anyway,
+    // but we keep the mapping deterministic and bounded.
+    const cos = dot / denom;
+    // Map cosine: clear negatives (penalize mismatch strongly), keep positives 0..1.
+    // Previous (cos+1)/2 was too lenient for "orthogonal" features.
+    return Math.max(0, cos);
+}
+
+function pushScaled(dst: number[], src: Float32Array, scale: number) {
+    for (let i = 0; i < src.length; i++) dst.push((src[i] ?? 0) * scale);
+}
+
+/**
+ * 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
+ */
+export function fingerprintToVectorV1(fp: MirFingerprintV1, weights: MirFingerprintVectorWeights = {}): Float32Array {
+    const wMel = weights.mel ?? 1;
+    const wTrans = weights.transient ?? 1;
+    const wMfcc = weights.mfcc ?? 1;
+
+    // --- mel block
+    const melBlock = new Float32Array(fp.mel.mean.length + fp.mel.variance.length);
+    melBlock.set(fp.mel.mean, 0);
+    melBlock.set(fp.mel.variance, fp.mel.mean.length);
+    normaliseL2InPlace(melBlock);
+
+    // --- transient block
+    const transBlock = new Float32Array([fp.onset.mean, fp.onset.max, fp.onset.peakDensityHz]);
+    normaliseL2InPlace(transBlock);
+
+    // --- optional mfcc block
+    let mfccBlock: Float32Array | null = null;
+    if (fp.mfcc) {
+        mfccBlock = new Float32Array(fp.mfcc.mean.length + fp.mfcc.variance.length);
+        mfccBlock.set(fp.mfcc.mean, 0);
+        mfccBlock.set(fp.mfcc.variance, fp.mfcc.mean.length);
+        normaliseL2InPlace(mfccBlock);
+    }
+
+    const out: number[] = [];
+    pushScaled(out, melBlock, wMel);
+    pushScaled(out, transBlock, wTrans);
+    if (mfccBlock) pushScaled(out, mfccBlock, wMfcc);
+
+    return new Float32Array(out);
+}
+
+export function similarityFingerprintV1(a: MirFingerprintV1, b: MirFingerprintV1, weights: MirFingerprintVectorWeights = {}): number {
+    const va = fingerprintToVectorV1(a, weights);
+    const vb = fingerprintToVectorV1(b, weights);
+    return cosineSimilarity(va, vb);
+}

package/src/types.ts

@@ -0,0 +1,105 @@
+export type MirBackend = "cpu" | "gpu";
+
+export type MirRunTimings = {
+    totalMs: number;
+    cpuMs?: number;
+    gpuMs?: number;
+};
+
+export type MirRunMeta = {
+    backend: MirBackend;
+    usedGpu: boolean;
+    timings: MirRunTimings;
+};
+
+export type Mir1DResult = {
+    kind: "1d";
+    times: Float32Array;
+    values: Float32Array;
+    meta: MirRunMeta;
+};
+
+export type Mir2DResult = {
+    kind: "2d";
+    times: Float32Array;
+    data: Float32Array[];
+    meta: MirRunMeta;
+};
+
+export type MirEvent = {
+    time: number;
+    strength: number;
+    index: number;
+};
+
+export type MirEventsResult = {
+    kind: "events";
+    times: Float32Array;
+    events: MirEvent[];
+    meta: MirRunMeta;
+};
+
+export type MirResult = Mir1DResult | Mir2DResult | MirEventsResult;
+
+// (moved above)
+
+export type MirFunctionId =
+    | "spectralCentroid"
+    | "spectralFlux"
+    | "melSpectrogram"
+    | "onsetEnvelope"
+    | "onsetPeaks"
+    | "hpssHarmonic"
+    | "hpssPercussive"
+    | "mfcc"
+    | "mfccDelta"
+    | "mfccDeltaDelta";
+
+export type MirRunRequest = {
+    fn: MirFunctionId;
+    spectrogram?: {
+        fftSize: number;
+        hopSize: number;
+        window: "hann";
+    };
+    mel?: {
+        nMels: number;
+        fMin?: number;
+        fMax?: number;
+    };
+    backend?: MirBackend;
+
+    // Optional per-run config. Kept explicit (not a dynamic schema).
+    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";
+        };
+    };
+};
+
+export type MirAudioPayload = {
+    sampleRate: number;
+    mono: Float32Array;
+};

package/src/util/display.ts

@@ -0,0 +1,80 @@
+/**
+ * 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]`.
+ */
+
+export type Spectrogram2D = Float32Array[]; // [frame][bin]
+
+export 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.
+ */
+export function spectrogramToDb(magnitudes2d: Spectrogram2D, options: SpectrogramToDbOptions = {}): Spectrogram2D {
+    const eps = options.epsilon ?? 1e-12;
+    const floorDb = options.floorDb;
+
+    const out: Float32Array[] = new Array(magnitudes2d.length);
+
+    for (let t = 0; t < magnitudes2d.length; t++) {
+        const row = magnitudes2d[t] ?? new Float32Array(0);
+        const dbRow = new Float32Array(row.length);
+
+        for (let k = 0; k < row.length; k++) {
+            const mag = row[k] ?? 0;
+            const db = 20 * Math.log10(Math.max(eps, mag));
+            dbRow[k] = floorDb !== undefined ? Math.max(floorDb, db) : db;
+        }
+
+        out[t] = dbRow;
+    }
+
+    return out;
+}
+
+/**
+ * Clamp a dB-scaled 2D array to a fixed range.
+ *
+ * The input is not mutated.
+ * Intended for visualisation only.
+ */
+export function clampDb(db2d: Spectrogram2D, minDb: number, maxDb: number): Spectrogram2D {
+    const out: Float32Array[] = new Array(db2d.length);
+
+    for (let t = 0; t < db2d.length; t++) {
+        const row = db2d[t] ?? new Float32Array(0);
+        const clamped = new Float32Array(row.length);
+
+        for (let k = 0; k < row.length; k++) {
+            const v = row[k] ?? 0;
+            clamped[k] = v < minDb ? minDb : v > maxDb ? maxDb : v;
+        }
+
+        out[t] = clamped;
+    }
+
+    return out;
+}

package/src/util/normalise.ts

@@ -0,0 +1,58 @@
+export 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]
+ */
+export function normaliseForWaveform(
+    data: Float32Array,
+    options: NormaliseForWaveformOptions = {}
+): Float32Array {
+    const center = options.center ?? false;
+
+    const targetMin = options.min ?? (center ? -1 : 0);
+    const targetMax = options.max ?? 1;
+
+    if (!Number.isFinite(targetMin) || !Number.isFinite(targetMax)) {
+        throw new Error("@octoseq/mir: normaliseForWaveform min/max must be finite");
+    }
+    if (targetMax === targetMin) {
+        throw new Error("@octoseq/mir: normaliseForWaveform max must differ from min");
+    }
+
+    let srcMin = Infinity;
+    let srcMax = -Infinity;
+    for (let i = 0; i < data.length; i++) {
+        const v = data[i] ?? 0;
+        if (v < srcMin) srcMin = v;
+        if (v > srcMax) srcMax = v;
+    }
+
+    // Degenerate or empty: return a constant line at the middle of the target range.
+    if (!Number.isFinite(srcMin) || !Number.isFinite(srcMax) || srcMax === srcMin) {
+        const out = new Float32Array(data.length);
+        const mid = (targetMin + targetMax) / 2;
+        out.fill(mid);
+        return out;
+    }
+
+    const out = new Float32Array(data.length);
+    const scale = (targetMax - targetMin) / (srcMax - srcMin);
+
+    for (let i = 0; i < data.length; i++) {
+        const v = data[i] ?? 0;
+        out[i] = targetMin + (v - srcMin) * scale;
+    }
+
+    return out;
+}

package/src/util/stats.ts

@@ -0,0 +1,25 @@
+export 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).
+ */
+export function minMax(values: ArrayLike<number>): MinMax {
+    const n = values.length >>> 0;
+    if (n === 0) return { min: Infinity, max: -Infinity };
+
+    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;
+    }
+
+    return { min, max };
+}