@siteed/audio-studio 3.0.0 → 3.0.2-beta.1

package/src/AudioAnalysis/audioFeaturesWasm.web.ts

@@ -0,0 +1,201 @@
+import type { AudioFeaturesWasmModule } from './audio-features-wasm'
+import { getMelSpectrogramWasmUrl } from './wasmConfig'
+
+export interface AudioFeaturesWasmResult {
+    spectralCentroid: number
+    spectralFlatness: number
+    spectralRolloff: number
+    spectralBandwidth: number
+    mfcc: number[]
+    chromagram: number[]
+}
+
+let modulePromise: Promise<AudioFeaturesWasmModule> | null = null
+
+function getModule(): Promise<AudioFeaturesWasmModule> {
+    if (!modulePromise) {
+        modulePromise = (async () => {
+            const url = getMelSpectrogramWasmUrl()
+            // webpackIgnore + @vite-ignore prevent bundlers from trying to resolve the URL
+            const mod = await import(/* webpackIgnore: true */ /* @vite-ignore */ url)
+            const factory = mod.default ?? mod
+            return factory() as Promise<AudioFeaturesWasmModule>
+        })().catch((err) => {
+            modulePromise = null
+            throw err
+        })
+    }
+    return modulePromise
+}
+
+// --- Struct layout for CAudioFeaturesResult (wasm32) ---
+// Offset  0: float spectralCentroid  (4 bytes)
+// Offset  4: float spectralFlatness  (4 bytes)
+// Offset  8: float spectralRolloff   (4 bytes)
+// Offset 12: float spectralBandwidth (4 bytes)
+// Offset 16: float* mfcc             (4 bytes pointer)
+// Offset 20: int mfccCount           (4 bytes)
+// Offset 24: float* chromagram       (4 bytes pointer)
+// Offset 28: int chromagramCount     (4 bytes)
+const STRUCT_SIZE = 32
+
+function readResult(
+    Module: AudioFeaturesWasmModule,
+    ptr: number
+): AudioFeaturesWasmResult {
+    const spectralCentroid = Module.getValue(ptr, 'float')
+    const spectralFlatness = Module.getValue(ptr + 4, 'float')
+    const spectralRolloff = Module.getValue(ptr + 8, 'float')
+    const spectralBandwidth = Module.getValue(ptr + 12, 'float')
+
+    const mfccPtr = Module.getValue(ptr + 16, 'i32')
+    const mfccCount = Module.getValue(ptr + 20, 'i32')
+    const chromaPtr = Module.getValue(ptr + 24, 'i32')
+    const chromaCount = Module.getValue(ptr + 28, 'i32')
+
+    const mfcc: number[] = []
+    if (mfccPtr && mfccCount > 0) {
+        const offset = mfccPtr >> 2
+        for (let i = 0; i < mfccCount; i++) {
+            mfcc.push(Module.HEAPF32[offset + i])
+        }
+    }
+
+    const chromagram: number[] = []
+    if (chromaPtr && chromaCount > 0) {
+        const offset = chromaPtr >> 2
+        for (let i = 0; i < chromaCount; i++) {
+            chromagram.push(Module.HEAPF32[offset + i])
+        }
+    }
+
+    return {
+        spectralCentroid,
+        spectralFlatness,
+        spectralRolloff,
+        spectralBandwidth,
+        mfcc,
+        chromagram,
+    }
+}
+
+// --- Streaming (per-frame) API ---
+
+let streamingModule: AudioFeaturesWasmModule | null = null
+let streamingFramePtr = 0
+let streamingFrameCapacity = 0
+let streamingResultPtr = 0
+
+/**
+ * Initialise the WASM streaming audio features processor.
+ * Call once before computeAudioFeaturesFrameWasm().
+ */
+export async function initAudioFeaturesWasm(
+    sampleRate: number,
+    fftLength = 1024,
+    nMfcc = 13,
+    nMelFilters = 26,
+    computeMfcc = true,
+    computeChroma = true
+): Promise<void> {
+    const Module = await getModule()
+    streamingModule = Module
+
+    Module._audio_features_init(
+        sampleRate,
+        fftLength,
+        nMfcc,
+        nMelFilters,
+        computeMfcc ? 1 : 0,
+        computeChroma ? 1 : 0
+    )
+
+    // Pre-allocate result struct on WASM heap
+    if (streamingResultPtr) Module._free(streamingResultPtr)
+    streamingResultPtr = Module._malloc(STRUCT_SIZE)
+    // Zero-initialize to prevent freeing garbage pointers on first use
+    Module.HEAPU8.fill(0, streamingResultPtr, streamingResultPtr + STRUCT_SIZE)
+
+    // Frame input buffer allocated on demand
+    streamingFrameCapacity = 0
+    streamingFramePtr = 0
+}
+
+/**
+ * Compute audio features for a single frame via WASM C++.
+ * Returns null if not initialised or on error.
+ */
+export function computeAudioFeaturesFrameWasm(
+    samples: Float32Array
+): AudioFeaturesWasmResult | null {
+    if (!streamingModule || !streamingResultPtr) return null
+    const Module = streamingModule
+
+    // (Re-)allocate frame input buffer if needed
+    if (samples.length > streamingFrameCapacity) {
+        if (streamingFramePtr) Module._free(streamingFramePtr)
+        streamingFramePtr = Module._malloc(samples.length * 4)
+        streamingFrameCapacity = samples.length
+    }
+
+    // Copy samples to WASM heap
+    Module.HEAPF32.set(samples, streamingFramePtr >> 2)
+
+    const ok = Module._audio_features_compute_frame(
+        streamingFramePtr,
+        samples.length,
+        streamingResultPtr
+    )
+    if (!ok) return null
+
+    const result = readResult(Module, streamingResultPtr)
+
+    // Free internal arrays (mfcc, chromagram) allocated by C
+    Module._audio_features_free_arrays(streamingResultPtr)
+
+    return result
+}
+
+// --- Batch API ---
+
+/**
+ * Compute audio features for a buffer of samples via WASM C++.
+ * Lazy-loads the WASM module on first call.
+ */
+export async function computeAudioFeaturesWasm(
+    audioData: Float32Array,
+    sampleRate: number,
+    fftLength = 1024,
+    nMfcc = 13,
+    nMelFilters = 26,
+    computeMfcc = true,
+    computeChroma = true
+): Promise<AudioFeaturesWasmResult> {
+    const Module = await getModule()
+
+    const numSamples = audioData.length
+    const inputPtr = Module._malloc(numSamples * 4)
+    Module.HEAPF32.set(audioData, inputPtr >> 2)
+
+    const resultPtr = Module._audio_features_compute(
+        inputPtr,
+        numSamples,
+        sampleRate,
+        fftLength,
+        nMfcc,
+        nMelFilters,
+        computeMfcc ? 1 : 0,
+        computeChroma ? 1 : 0
+    )
+
+    Module._free(inputPtr)
+
+    if (resultPtr === 0) {
+        throw new Error('audio_features_compute returned null')
+    }
+
+    const result = readResult(Module, resultPtr)
+    Module._audio_features_free(resultPtr)
+
+    return result
+}

package/src/AudioAnalysis/melSpectrogramWasm.ts

@@ -1,179 +1,33 @@
-import type { MelSpectrogramWasmModule } from './mel-spectrogram-wasm'
+// Native stub — WASM mel spectrogram is web-only.
+// These functions are only called in web contexts; on native, the C++ TurboModule handles mel spectrograms.
 
-let modulePromise: Promise<MelSpectrogramWasmModule> | null = null
-
-function getModule(): Promise<MelSpectrogramWasmModule> {
-    if (!modulePromise) {
-        modulePromise = (async () => {
-            // Dynamic import of the prebuilt SINGLE_FILE Emscripten module
-            // @ts-expect-error -- prebuilt Emscripten JS glue has no .d.ts
-            const mod = await import('../../prebuilt/wasm/mel-spectrogram.js')
-            const factory = mod.default ?? mod
-            return factory() as Promise<MelSpectrogramWasmModule>
-        })().catch((err) => {
-            modulePromise = null
-            throw err
-        })
-    }
-    return modulePromise
-}
-
-// --- Streaming (per-frame) API for live mel spectrogram ---
-
-let streamingModule: MelSpectrogramWasmModule | null = null
-let streamingNMels = 0
-let streamingFramePtr = 0
-let streamingMelPtr = 0
-let streamingFrameCapacity = 0
-
-/**
- * Initialise the WASM streaming processor. Call once before computeMelFrame().
- * Re-initialises only when config changes.
- */
 export async function initMelStreamingWasm(
-    sampleRate: number,
-    nMels = 128,
-    fftLength = 2048,
-    windowSizeSamples = 400,
-    hopLengthSamples = 160,
-    fMin = 0,
-    fMax = 0
+    _sampleRate: number,
+    _nMels?: number,
+    _fftLength?: number,
+    _windowSizeSamples?: number,
+    _hopLengthSamples?: number,
+    _fMin?: number,
+    _fMax?: number
 ): Promise<void> {
-    const Module = await getModule()
-    streamingModule = Module
-    const actualFMax = fMax > 0 ? fMax : sampleRate / 2
-    Module._mel_spectrogram_init(
-        sampleRate,
-        fftLength,
-        windowSizeSamples,
-        hopLengthSamples,
-        nMels,
-        fMin,
-        actualFMax,
-        0 /* hann */
-    )
-    streamingNMels = nMels
-
-    // Pre-allocate output buffer (fixed size)
-    if (streamingMelPtr) Module._free(streamingMelPtr)
-    streamingMelPtr = Module._malloc(nMels * 4)
-
-    // Frame input buffer allocated on demand in computeMelFrame
-    streamingFrameCapacity = 0
-    streamingFramePtr = 0
+    throw new Error('WASM mel spectrogram is not available on native')
 }
 
-/**
- * Compute a single mel spectrogram frame from raw PCM samples via WASM C++.
- * Returns null if not initialised or on error.
- */
-export function computeMelFrameWasm(samples: Float32Array): number[] | null {
-    if (!streamingModule || !streamingMelPtr) return null
-    const Module = streamingModule
-
-    // (Re-)allocate frame input buffer if needed
-    if (samples.length > streamingFrameCapacity) {
-        if (streamingFramePtr) Module._free(streamingFramePtr)
-        streamingFramePtr = Module._malloc(samples.length * 4)
-        streamingFrameCapacity = samples.length
-    }
-
-    // Copy samples to WASM heap
-    Module.HEAPF32.set(samples, streamingFramePtr >> 2)
-
-    const ok = Module._mel_spectrogram_compute_frame(
-        streamingFramePtr,
-        samples.length,
-        streamingMelPtr
-    )
-    if (!ok) return null
-
-    // Read mel output from WASM heap
-    const offset = streamingMelPtr >> 2
-    const result = new Array(streamingNMels)
-    for (let i = 0; i < streamingNMels; i++) {
-        result[i] = Module.HEAPF32[offset + i]
-    }
-    return result
+export function computeMelFrameWasm(_samples: Float32Array): number[] | null {
+    return null
 }
 
-/**
- * Computes a mel spectrogram via the WASM-compiled C++ implementation.
- * Lazy-loads the WASM module on first call.
- */
 export async function computeMelSpectrogramWasm(
-    audioData: Float32Array,
-    sampleRate: number,
-    nMels: number,
-    windowSizeSamples: number,
-    hopLengthSamples: number,
-    fMin: number,
-    fMax: number,
-    windowType: 'hann' | 'hamming',
-    normalize: boolean,
-    logScale: boolean
+    _audioData: Float32Array,
+    _sampleRate: number,
+    _nMels: number,
+    _windowSizeSamples: number,
+    _hopLengthSamples: number,
+    _fMin: number,
+    _fMax: number,
+    _windowType: 'hann' | 'hamming',
+    _normalize: boolean,
+    _logScale: boolean
 ): Promise<number[][]> {
-    const Module = await getModule()
-
-    const fftLength = 2048
-    const windowTypeInt = windowType === 'hamming' ? 1 : 0
-
-    // Allocate input buffer on WASM heap
-    const numSamples = audioData.length
-    const inputPtr = Module._malloc(numSamples * 4) // 4 bytes per float
-    Module.HEAPF32.set(audioData, inputPtr >> 2)
-
-    // Call the C bridge
-    const resultPtr = Module._mel_spectrogram_compute(
-        inputPtr,
-        numSamples,
-        sampleRate,
-        fftLength,
-        windowSizeSamples,
-        hopLengthSamples,
-        nMels,
-        fMin,
-        fMax,
-        windowTypeInt,
-        logScale ? 1 : 0,
-        normalize ? 1 : 0
-    )
-
-    // Free input buffer
-    Module._free(inputPtr)
-
-    if (resultPtr === 0) {
-        throw new Error(
-            'mel_spectrogram_compute returned null (too few samples?)'
-        )
-    }
-
-    // Read CMelSpectrogramResult struct (wasm32 pointers are 4 bytes)
-    // struct layout: { float* data (offset 0), int timeSteps (offset 4), int nMels (offset 8) }
-    const dataPtr = Module.getValue(resultPtr, 'i32')
-    const timeSteps = Module.getValue(resultPtr + 4, 'i32')
-    const resultNMels = Module.getValue(resultPtr + 8, 'i32')
-
-    if (!dataPtr || timeSteps <= 0 || resultNMels <= 0) {
-        Module._mel_spectrogram_free(resultPtr)
-        throw new Error(
-            'mel_spectrogram_compute returned invalid result struct'
-        )
-    }
-
-    // Copy spectrogram data to JS arrays
-    const spectrogram: number[][] = []
-    const heapOffset = dataPtr >> 2 // float32 offset into HEAPF32
-    for (let t = 0; t < timeSteps; t++) {
-        const row = new Array(resultNMels)
-        for (let m = 0; m < resultNMels; m++) {
-            row[m] = Module.HEAPF32[heapOffset + t * resultNMels + m]
-        }
-        spectrogram.push(row)
-    }
-
-    // Free the C result
-    Module._mel_spectrogram_free(resultPtr)
-
-    return spectrogram
+    throw new Error('WASM mel spectrogram is not available on native')
 }

package/src/AudioAnalysis/melSpectrogramWasm.web.ts

@@ -0,0 +1,184 @@
+import type { MelSpectrogramWasmModule } from './mel-spectrogram-wasm'
+import { getMelSpectrogramWasmUrl, _registerModuleReset } from './wasmConfig'
+
+let modulePromise: Promise<MelSpectrogramWasmModule> | null = null
+
+_registerModuleReset(() => {
+    modulePromise = null
+})
+
+function getModule(): Promise<MelSpectrogramWasmModule> {
+    if (!modulePromise) {
+        modulePromise = (async () => {
+            const url = getMelSpectrogramWasmUrl()
+            // webpackIgnore + @vite-ignore prevent bundlers from trying to resolve the URL
+            const mod = await import(/* webpackIgnore: true */ /* @vite-ignore */ url)
+            const factory = mod.default ?? mod
+            return factory() as Promise<MelSpectrogramWasmModule>
+        })().catch((err) => {
+            modulePromise = null
+            throw err
+        })
+    }
+    return modulePromise
+}
+
+// --- Streaming (per-frame) API for live mel spectrogram ---
+
+let streamingModule: MelSpectrogramWasmModule | null = null
+let streamingNMels = 0
+let streamingFramePtr = 0
+let streamingMelPtr = 0
+let streamingFrameCapacity = 0
+
+/**
+ * Initialise the WASM streaming processor. Call once before computeMelFrame().
+ * Re-initialises only when config changes.
+ */
+export async function initMelStreamingWasm(
+    sampleRate: number,
+    nMels = 128,
+    fftLength = 2048,
+    windowSizeSamples = 400,
+    hopLengthSamples = 160,
+    fMin = 0,
+    fMax = 0
+): Promise<void> {
+    const Module = await getModule()
+    streamingModule = Module
+    const actualFMax = fMax > 0 ? fMax : sampleRate / 2
+    Module._mel_spectrogram_init(
+        sampleRate,
+        fftLength,
+        windowSizeSamples,
+        hopLengthSamples,
+        nMels,
+        fMin,
+        actualFMax,
+        0 /* hann */
+    )
+    streamingNMels = nMels
+
+    // Pre-allocate output buffer (fixed size)
+    if (streamingMelPtr) Module._free(streamingMelPtr)
+    streamingMelPtr = Module._malloc(nMels * 4)
+
+    // Frame input buffer allocated on demand in computeMelFrame
+    streamingFrameCapacity = 0
+    streamingFramePtr = 0
+}
+
+/**
+ * Compute a single mel spectrogram frame from raw PCM samples via WASM C++.
+ * Returns null if not initialised or on error.
+ */
+export function computeMelFrameWasm(samples: Float32Array): number[] | null {
+    if (!streamingModule || !streamingMelPtr) return null
+    const Module = streamingModule
+
+    // (Re-)allocate frame input buffer if needed
+    if (samples.length > streamingFrameCapacity) {
+        if (streamingFramePtr) Module._free(streamingFramePtr)
+        streamingFramePtr = Module._malloc(samples.length * 4)
+        streamingFrameCapacity = samples.length
+    }
+
+    // Copy samples to WASM heap
+    Module.HEAPF32.set(samples, streamingFramePtr >> 2)
+
+    const ok = Module._mel_spectrogram_compute_frame(
+        streamingFramePtr,
+        samples.length,
+        streamingMelPtr
+    )
+    if (!ok) return null
+
+    // Read mel output from WASM heap
+    const offset = streamingMelPtr >> 2
+    const result = new Array(streamingNMels)
+    for (let i = 0; i < streamingNMels; i++) {
+        result[i] = Module.HEAPF32[offset + i]
+    }
+    return result
+}
+
+/**
+ * Computes a mel spectrogram via the WASM-compiled C++ implementation.
+ * Lazy-loads the WASM module on first call.
+ */
+export async function computeMelSpectrogramWasm(
+    audioData: Float32Array,
+    sampleRate: number,
+    nMels: number,
+    windowSizeSamples: number,
+    hopLengthSamples: number,
+    fMin: number,
+    fMax: number,
+    windowType: 'hann' | 'hamming',
+    normalize: boolean,
+    logScale: boolean
+): Promise<number[][]> {
+    const Module = await getModule()
+
+    const fftLength = 2048
+    const windowTypeInt = windowType === 'hamming' ? 1 : 0
+
+    // Allocate input buffer on WASM heap
+    const numSamples = audioData.length
+    const inputPtr = Module._malloc(numSamples * 4) // 4 bytes per float
+    Module.HEAPF32.set(audioData, inputPtr >> 2)
+
+    // Call the C bridge
+    const resultPtr = Module._mel_spectrogram_compute(
+        inputPtr,
+        numSamples,
+        sampleRate,
+        fftLength,
+        windowSizeSamples,
+        hopLengthSamples,
+        nMels,
+        fMin,
+        fMax,
+        windowTypeInt,
+        logScale ? 1 : 0,
+        normalize ? 1 : 0
+    )
+
+    // Free input buffer
+    Module._free(inputPtr)
+
+    if (resultPtr === 0) {
+        throw new Error(
+            'mel_spectrogram_compute returned null (too few samples?)'
+        )
+    }
+
+    // Read CMelSpectrogramResult struct (wasm32 pointers are 4 bytes)
+    // struct layout: { float* data (offset 0), int timeSteps (offset 4), int nMels (offset 8) }
+    const dataPtr = Module.getValue(resultPtr, 'i32')
+    const timeSteps = Module.getValue(resultPtr + 4, 'i32')
+    const resultNMels = Module.getValue(resultPtr + 8, 'i32')
+
+    if (!dataPtr || timeSteps <= 0 || resultNMels <= 0) {
+        Module._mel_spectrogram_free(resultPtr)
+        throw new Error(
+            'mel_spectrogram_compute returned invalid result struct'
+        )
+    }
+
+    // Copy spectrogram data to JS arrays
+    const spectrogram: number[][] = []
+    const heapOffset = dataPtr >> 2 // float32 offset into HEAPF32
+    for (let t = 0; t < timeSteps; t++) {
+        const row = new Array(resultNMels)
+        for (let m = 0; m < resultNMels; m++) {
+            row[m] = Module.HEAPF32[heapOffset + t * resultNMels + m]
+        }
+        spectrogram.push(row)
+    }
+
+    // Free the C result
+    Module._mel_spectrogram_free(resultPtr)
+
+    return spectrogram
+}

package/src/AudioAnalysis/wasmConfig.ts

@@ -0,0 +1,24 @@
+// Version is inlined here — keep in sync with package.json when releasing.
+// The publish.sh script should bump this string alongside package.json.
+const WASM_VERSION = '3.0.2'
+// jsDelivr syncs from npm automatically within ~5 min of publish.
+// GitHub release fallback (attach mel-spectrogram.js as a release asset):
+//   https://github.com/deeeed/audiolab/releases/download/@siteed/audio-studio@VERSION/mel-spectrogram.js
+// To use the fallback: setMelSpectrogramWasmUrl('<url>') before any mel-spectrogram API call.
+const DEFAULT_WASM_CDN = `https://cdn.jsdelivr.net/npm/@siteed/audio-studio@${WASM_VERSION}/prebuilt/wasm/mel-spectrogram.js`
+
+let _wasmUrl: string = DEFAULT_WASM_CDN
+let _modulePromiseReset: (() => void) | null = null
+
+export function _registerModuleReset(fn: () => void): void {
+    _modulePromiseReset = fn
+}
+
+export function setMelSpectrogramWasmUrl(url: string): void {
+    _wasmUrl = url
+    _modulePromiseReset?.() // invalidate cached module so next call re-fetches
+}
+
+export function getMelSpectrogramWasmUrl(): string {
+    return _wasmUrl
+}

package/src/index.ts

@@ -43,6 +43,8 @@ export { AudioDeviceManager, audioDeviceManager } from './AudioDeviceManager'
 // Export useAudioDevices hook
 export { useAudioDevices } from './hooks/useAudioDevices'
 
+export { setMelSpectrogramWasmUrl } from './AudioAnalysis/wasmConfig'
+
 export {
     AudioRecorderProvider,
     AudioStudioModule,