@fugood/node-whisper-wasm 1.0.19 → 1.0.20

package/README.md

@@ -1,13 +1,17 @@
 # @fugood/node-whisper-wasm
 
-Browser WASM package for `@fugood/whisper.node`.
+Browser WASM implementation package for `@fugood/whisper.node`. Application
+code should import `@fugood/whisper.node`; this package is pulled in by the main
+package for browser builds.
 
 The package exposes the same high-level context API as the native packages, but
 model and audio file paths are fetched as URLs and copied into the Emscripten
 filesystem before inference.
 
 ```js
-const whisper = await WhisperNodeWasm.initWhisper({
+import { initWhisper } from '@fugood/whisper.node'
+
+const whisper = await initWhisper({
   filePath: 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin',
   useGpu: false,
 })
@@ -23,18 +27,29 @@ await whisper.release()
 The WASM build uses pthreads, so browsers must serve the page with COOP/COEP
 headers and expose `SharedArrayBuffer`. Whisper transcription defaults to up to
 8 threads based on browser hardware concurrency; pass `maxThreads` to override
-it. Browser pages run model loading, transcription, benchmarks, and VAD in a
-dedicated worker by default so the UI thread can keep rendering. Use
-`configureWasm({ worker: false })` only when you explicitly need the old
-in-thread runtime, or pass `workerUrl`, `indexScriptUrl`, and `runtimeScriptUrl`
-when serving the package files from custom URLs. Set `useGpu: true` only with a
-package built using `GGML_WEBGPU=ON` and a browser that exposes `navigator.gpu`.
-VAD currently falls back to CPU in the browser package because the Silero VAD
-graph hits unsupported WebGPU ops.
-
-The default build emits `whisper-node.js` and `whisper-node.wasm`. Use
-`bash scripts/build-wasm.sh --single-file` only when you want the WASM binary
-embedded into `whisper-node.js`. Modern Emscripten embeds the pthread worker
-bootstrap in the main JS file, so a separate `whisper-node.worker.js` is not
-expected. The package worker that keeps UI work off the main thread is
-`worker.js`.
+it. Browser WASM clamps `maxThreads` to the compiled pool limit of 8. Browser
+pages run model loading, transcription, benchmarks, and VAD in a dedicated
+module worker by default so the UI thread can keep rendering. Use the main
+`whisper.node` package entrypoint in browser code:
+
+```js
+import { configureWasm, initWhisper } from '@fugood/whisper.node'
+```
+
+Use `configureWasm({ worker: false })` only when you explicitly need the
+in-thread runtime, or pass `workerPath`, `jsPath`, and `wasmPath` when serving
+the package files from custom URLs. The older `workerUrl` and
+`runtimeScriptUrl` option names still work. Model downloads are cached in
+browser Cache Storage by default. Pass `cacheModel: false` to disable persistent
+caching, `modelCacheName` to isolate the cache namespace, or `modelCacheKey`
+when the fetch URL is a proxy or signed URL but should reuse the same cached
+model. Set `useGpu: true` only with a package built using `GGML_WEBGPU=ON` and a
+browser that exposes `navigator.gpu`. VAD currently falls back to CPU in the
+browser package because the Silero VAD graph hits unsupported WebGPU ops.
+
+The default build emits `wasm/whisper-node.js` and `wasm/whisper-node.wasm`.
+Use `bash scripts/build-wasm.sh --single-file` only when you want the WASM
+binary embedded into `wasm/whisper-node.js`. Modern Emscripten embeds the
+pthread worker bootstrap in the main JS file, so a separate
+`whisper-node.worker.js` is not expected. The package module worker that keeps
+UI work off the main thread is `worker.js`.

package/index.d.ts

@@ -4,6 +4,9 @@ export interface NativeContextOptions {
   useFlashAttn?: boolean
   useGpu?: boolean
   maxModelBytes?: number
+  cacheModel?: boolean
+  modelCacheName?: string
+  modelCacheKey?: string
   worker?: boolean
 }
 
@@ -13,6 +16,9 @@ export interface NativeVadContextOptions {
   useGpu?: boolean
   nThreads?: number
   maxModelBytes?: number
+  cacheModel?: boolean
+  modelCacheName?: string
+  modelCacheKey?: string
   worker?: boolean
 }
 
@@ -136,12 +142,18 @@ export interface Module {
 export interface WasmRuntimeOptions {
   worker?: boolean
   workerUrl?: string
+  workerPath?: string
   indexScriptUrl?: string
   scriptUrl?: string
   runtimeScriptUrl?: string
+  jsPath?: string
+  wasmPath?: string
   locateFileBaseUrl?: string
   locateFile?: (path: string, prefix: string) => string
   mainScriptUrlOrBlob?: string | Blob
+  modelCacheName?: string
+  moduleFactory?: (options?: Record<string, unknown>) => Promise<unknown> | unknown
+  moduleOptions?: Record<string, unknown>
   print?: (text: string) => void
   printErr?: (text: string) => void
 }
@@ -149,6 +161,13 @@ export interface WasmRuntimeOptions {
 export declare const WhisperContext: Module['WhisperContext']
 export declare const WhisperVadContext: Module['WhisperVadContext']
 export declare const DEFAULT_WASM_MODEL_SIZE_LIMIT_BYTES: number
+export declare const MAX_WASM_THREADS: number
+export declare const WASM_CONFIG_PATHS: {
+  index: string
+  js: string
+  wasm: string
+  worker: string
+}
 
 export declare function configureWasm(options: WasmRuntimeOptions): void
 export declare function loadWasmModule(): Promise<unknown>
@@ -178,6 +197,8 @@ declare const _default: {
   toggleNativeLog: typeof toggleNativeLog
   addNativeLogListener: typeof addNativeLogListener
   DEFAULT_WASM_MODEL_SIZE_LIMIT_BYTES: typeof DEFAULT_WASM_MODEL_SIZE_LIMIT_BYTES
+  MAX_WASM_THREADS: typeof MAX_WASM_THREADS
+  WASM_CONFIG_PATHS: typeof WASM_CONFIG_PATHS
 }
 
 export default _default

package/index.js

@@ -1,33 +1,33 @@
-(function (root, factory) {
-  if (typeof module === 'object' && module.exports) {
-    module.exports = factory(function () {
-      return require('./whisper-node.js')
-    }, root)
-  } else {
-    root.WhisperNodeWasm = factory(function () {
-      return root.createWhisperNodeModule
-    }, root)
-  }
-})(
+const root =
   typeof globalThis !== 'undefined'
     ? globalThis
     : typeof self !== 'undefined'
       ? self
       : typeof window !== 'undefined'
         ? window
-        : this,
-  function (loadModuleFactory, root) {
+        : undefined
+
+export const WASM_CONFIG_PATHS = {
+  index: new URL('./index.js', import.meta.url).href,
+  js: new URL('./wasm/whisper-node.js', import.meta.url).href,
+  wasm: new URL('./wasm/whisper-node.wasm', import.meta.url).href,
+  worker: new URL('./worker.js', import.meta.url).href,
+}
+
+const createWhisperNodeApi = function (root) {
     'use strict'
 
     var SAMPLE_RATE = 16000
     var MIB = 1024 * 1024
     var FIREFOX_MODEL_LIMIT_BYTES = 256 * MIB
     var MODEL_MEMORY_RATIO = 0.75
+    var MAX_WASM_THREADS = 8
+    var DEFAULT_MODEL_CACHE_NAME = 'whisper.node.wasm.models'
 
     var runtimePromise = null
     var runtimeOptions = {}
     var workerProxyPromise = null
-    var capturedScriptUrl = getCurrentScriptUrl()
+    var capturedScriptUrl = WASM_CONFIG_PATHS.index
     var modelCache = Object.create(null)
     var logEnabled = false
     var logListeners = []
@@ -40,19 +40,8 @@
       runtimeOptions = Object.assign({}, runtimeOptions, options || {})
     }
 
-    function getCurrentScriptUrl() {
-      if (
-        root.document &&
-        root.document.currentScript &&
-        root.document.currentScript.src
-      ) {
-        return root.document.currentScript.src
-      }
-      return null
-    }
-
     function isBrowserLike() {
-      return typeof root.window !== 'undefined' || typeof root.importScripts === 'function'
+      return typeof root.window !== 'undefined' || typeof root.WorkerGlobalScope !== 'undefined'
     }
 
     function isMainBrowserThread() {
@@ -80,19 +69,27 @@
     }
 
     function getRuntimeScriptUrl(indexScriptUrl) {
-      var configured = runtimeOptions.runtimeScriptUrl
+      var configured = runtimeOptions.jsPath || runtimeOptions.runtimeScriptUrl
       if (configured) {
         return resolveUrl(configured, indexScriptUrl)
       }
-      return indexScriptUrl ? resolveUrl('whisper-node.js', indexScriptUrl) : null
+      return WASM_CONFIG_PATHS.js
+    }
+
+    function getWasmBinaryUrl(runtimeScriptUrl) {
+      var configured = runtimeOptions.wasmPath
+      if (configured) {
+        return resolveUrl(configured, runtimeScriptUrl)
+      }
+      return WASM_CONFIG_PATHS.wasm
     }
 
     function getWorkerScriptUrl(indexScriptUrl) {
-      var configured = runtimeOptions.workerUrl
+      var configured = runtimeOptions.workerPath || runtimeOptions.workerUrl
       if (configured) {
         return resolveUrl(configured, indexScriptUrl)
       }
-      return indexScriptUrl ? resolveUrl('worker.js', indexScriptUrl) : null
+      return WASM_CONFIG_PATHS.worker
     }
 
     function shouldUseWorker(options) {
@@ -108,11 +105,16 @@
       var blocked = {
         worker: true,
         workerUrl: true,
+        workerPath: true,
         indexScriptUrl: true,
         scriptUrl: true,
         runtimeScriptUrl: true,
+        jsPath: true,
+        wasmPath: true,
         locateFileBaseUrl: true,
         locateFile: true,
+        moduleFactory: true,
+        moduleOptions: true,
         print: true,
         printErr: true,
         mainScriptUrlOrBlob: true,
@@ -151,35 +153,74 @@
       if (!runtimePromise) {
         assertThreadSupport()
 
-        var moduleFactory = loadModuleFactory()
-        if (moduleFactory && moduleFactory.default) {
-          moduleFactory = moduleFactory.default
-        }
-        if (typeof moduleFactory !== 'function') {
-          throw new Error(
-            'Failed to load whisper.node WASM runtime. Make sure whisper-node.js is built and loaded before index.js.',
-          )
-        }
-
-        var options = Object.assign({}, runtimeOptions)
-        var userPrint = options.print
-        var userPrintErr = options.printErr
+        runtimePromise = (async function () {
+          var indexScriptUrl = getIndexScriptUrl()
+          var runtimeScriptUrl = getRuntimeScriptUrl(indexScriptUrl)
+          var wasmUrl = getWasmBinaryUrl(runtimeScriptUrl)
+          var moduleFactory = runtimeOptions.moduleFactory
+
+          if (!moduleFactory) {
+            var runtimeModule = await import(runtimeScriptUrl)
+            moduleFactory =
+              runtimeModule.default ||
+              runtimeModule.createWhisperNodeModule ||
+              runtimeModule
+          }
+          if (typeof moduleFactory !== 'function') {
+            throw new Error(
+              'Failed to load whisper.node WASM runtime. Make sure wasm/whisper-node.js is built and included in the package.',
+            )
+          }
 
-        options.noInitialRun = true
-        options.print = function (text) {
-          emitLog('INFO', String(text))
-          if (typeof userPrint === 'function') {
-            userPrint(text)
+          var options = Object.assign(
+            {},
+            runtimeOptions.moduleOptions || {},
+            runtimeOptions,
+          )
+          var userPrint = options.print
+          var userPrintErr = options.printErr
+          var userLocateFile = options.locateFile
+          var locateFileBaseUrl =
+            options.locateFileBaseUrl || resolveUrl('.', runtimeScriptUrl)
+
+          delete options.moduleFactory
+          delete options.moduleOptions
+          delete options.worker
+          delete options.workerUrl
+          delete options.workerPath
+          delete options.indexScriptUrl
+          delete options.scriptUrl
+          delete options.runtimeScriptUrl
+          delete options.jsPath
+          delete options.wasmPath
+          delete options.locateFileBaseUrl
+
+          options.noInitialRun = true
+          options.mainScriptUrlOrBlob = options.mainScriptUrlOrBlob || runtimeScriptUrl
+          options.locateFile = function (path, prefix) {
+            if (path === 'whisper-node.wasm' || path.slice(-5) === '.wasm') {
+              return wasmUrl
+            }
+            if (typeof userLocateFile === 'function') {
+              return userLocateFile(path, prefix)
+            }
+            return resolveUrl(path, locateFileBaseUrl || prefix)
           }
-        }
-        options.printErr = function (text) {
-          emitLog('ERROR', String(text))
-          if (typeof userPrintErr === 'function') {
-            userPrintErr(text)
+          options.print = function (text) {
+            emitLog('INFO', String(text))
+            if (typeof userPrint === 'function') {
+              userPrint(text)
+            }
+          }
+          options.printErr = function (text) {
+            emitLog('ERROR', String(text))
+            if (typeof userPrintErr === 'function') {
+              userPrintErr(text)
+            }
           }
-        }
 
-        runtimePromise = Promise.resolve(moduleFactory(options))
+          return moduleFactory(options)
+        })()
       }
 
       return runtimePromise
@@ -213,6 +254,7 @@
     function createWorkerProxy() {
       var indexScriptUrl = getIndexScriptUrl()
       var runtimeScriptUrl = getRuntimeScriptUrl(indexScriptUrl)
+      var wasmUrl = getWasmBinaryUrl(runtimeScriptUrl)
       var workerScriptUrl = getWorkerScriptUrl(indexScriptUrl)
 
       if (!indexScriptUrl || !runtimeScriptUrl || !workerScriptUrl) {
@@ -220,6 +262,7 @@
       }
 
       var worker = new root.Worker(workerScriptUrl, {
+        type: 'module',
         name: 'whisper.node.wasm',
       })
       var proxy = {
@@ -323,6 +366,7 @@
         {
           indexScriptUrl: indexScriptUrl,
           runtimeScriptUrl: runtimeScriptUrl,
+          wasmPath: wasmUrl,
           runtimeOptions: getWorkerRuntimeOptions(),
           locateFileBaseUrl:
             runtimeOptions.locateFileBaseUrl || resolveUrl('.', runtimeScriptUrl),
@@ -366,6 +410,39 @@
       throw new Error('fetch is required to load models or audio by URL')
     }
 
+    function getCacheStorage() {
+      return root.caches || null
+    }
+
+    function isModelCacheEnabled(options) {
+      return !options || options.cacheModel !== false
+    }
+
+    function getModelCacheName(options) {
+      return (
+        (options && options.modelCacheName) ||
+        runtimeOptions.modelCacheName ||
+        DEFAULT_MODEL_CACHE_NAME
+      )
+    }
+
+    function getModelCacheKey(source, options) {
+      var key = (options && options.modelCacheKey) || source
+      try {
+        return new URL(key, root.location && root.location.href).href
+      } catch (_) {
+        return key
+      }
+    }
+
+    function canUseModelCache(options) {
+      return (
+        isModelCacheEnabled(options) &&
+        !!getCacheStorage() &&
+        typeof root.Response === 'function'
+      )
+    }
+
     function formatBytes(bytes) {
       if (bytes >= 1024 * MIB) {
         return (bytes / (1024 * MIB)).toFixed(2) + ' GiB'
@@ -497,6 +574,106 @@
       return buffer
     }
 
+    async function readCachedModel(source, limit, options) {
+      if (!canUseModelCache(options)) {
+        return null
+      }
+
+      var cacheName = getModelCacheName(options)
+      var cacheKey = getModelCacheKey(source, options)
+
+      try {
+        var cache = await getCacheStorage().open(cacheName)
+        var response = await cache.match(cacheKey)
+        if (!response) {
+          return null
+        }
+
+        var buffer = await response.arrayBuffer()
+        if (limit) {
+          assertModelSize(buffer.byteLength, limit, source)
+        }
+        emitLog('INFO', 'Loaded cached WASM model: ' + source)
+        return {
+          buffer: buffer,
+          cacheHit: true,
+          cacheStored: false,
+          cacheName: cacheName,
+          cacheKey: cacheKey,
+        }
+      } catch (error) {
+        emitLog(
+          'WARN',
+          'Failed to read cached WASM model ' +
+            source +
+            ': ' +
+            (error && error.message ? error.message : String(error)),
+        )
+        return null
+      }
+    }
+
+    async function writeCachedModel(source, buffer, options) {
+      if (!canUseModelCache(options)) {
+        return {
+          cacheStored: false,
+          cacheName: null,
+          cacheKey: null,
+        }
+      }
+
+      var cacheName = getModelCacheName(options)
+      var cacheKey = getModelCacheKey(source, options)
+
+      try {
+        var cache = await getCacheStorage().open(cacheName)
+        await cache.put(
+          cacheKey,
+          new root.Response(buffer.slice(0), {
+            headers: {
+              'content-type': 'application/octet-stream',
+            },
+          }),
+        )
+        emitLog('INFO', 'Cached WASM model download: ' + source)
+        return {
+          cacheStored: true,
+          cacheName: cacheName,
+          cacheKey: cacheKey,
+        }
+      } catch (error) {
+        emitLog(
+          'WARN',
+          'Failed to cache WASM model ' +
+            source +
+            ': ' +
+            (error && error.message ? error.message : String(error)),
+        )
+        return {
+          cacheStored: false,
+          cacheName: cacheName,
+          cacheKey: cacheKey,
+        }
+      }
+    }
+
+    async function fetchModelArrayBuffer(source, limit, options) {
+      var cached = await readCachedModel(source, limit, options)
+      if (cached) {
+        return cached
+      }
+
+      var buffer = await fetchArrayBuffer(source, limit)
+      var cache = await writeCachedModel(source, buffer, options)
+      return {
+        buffer: buffer,
+        cacheHit: false,
+        cacheStored: cache.cacheStored,
+        cacheName: cache.cacheName,
+        cacheKey: cache.cacheKey,
+      }
+    }
+
     async function ensureModel(runtime, source, kind, options) {
       if (!source) {
         throw new Error('Model path is required')
@@ -510,8 +687,8 @@
       if (!modelCache[cacheKey]) {
         modelCache[cacheKey] = (async function () {
           var limit = getModelSizeLimit(runtime, options)
-          var buffer = await fetchArrayBuffer(source, limit)
-          var bytes = new Uint8Array(buffer)
+          var loaded = await fetchModelArrayBuffer(source, limit, options)
+          var bytes = new Uint8Array(loaded.buffer)
           var virtualPath =
             '/models/' + kind + '-' + hashString(source) + '-' + basenameFromUrl(source)
 
@@ -521,6 +698,10 @@
           return {
             virtualPath: virtualPath,
             bytes: bytes.byteLength,
+            cacheHit: loaded.cacheHit,
+            cacheStored: loaded.cacheStored,
+            cacheName: loaded.cacheName,
+            cacheKey: loaded.cacheKey,
           }
         })()
       }
@@ -562,8 +743,27 @@
       return value
     }
 
-    function normalizeTranscribeOptions(options) {
+    function normalizeMaxThreads(value) {
+      var nThreads = Number(value)
+      if (!Number.isFinite(nThreads) || nThreads <= 0) {
+        return null
+      }
+      return Math.max(1, Math.min(MAX_WASM_THREADS, Math.floor(nThreads)))
+    }
+
+    function normalizeThreadOptions(options) {
       var normalized = Object.assign({}, options || {})
+      var maxThreads = normalizeMaxThreads(normalized.maxThreads)
+      if (maxThreads) {
+        normalized.maxThreads = maxThreads
+      } else {
+        delete normalized.maxThreads
+      }
+      return normalized
+    }
+
+    function normalizeTranscribeOptions(options) {
+      var normalized = normalizeThreadOptions(options)
       if (typeof normalized.onProgress !== 'function') {
         delete normalized.onProgress
       }
@@ -574,7 +774,7 @@
     }
 
     function splitTranscribeOptions(options) {
-      var normalized = Object.assign({}, options || {})
+      var normalized = normalizeThreadOptions(options)
       var callbacks = {}
 
       if (typeof normalized.onProgress === 'function') {
@@ -966,6 +1166,10 @@
         useGpu: useGpu,
         useFlashAttn: options.useFlashAttn === true,
         bytes: model.bytes,
+        cacheHit: model.cacheHit,
+        cacheStored: model.cacheStored,
+        cacheName: model.cacheName,
+        cacheKey: model.cacheKey,
         wasm: true,
       })
     }
@@ -1168,6 +1372,10 @@
         useGpu: useGpu,
         nThreads: init.nThreads,
         bytes: model.bytes,
+        cacheHit: model.cacheHit,
+        cacheStored: model.cacheStored,
+        cacheName: model.cacheName,
+        cacheKey: model.cacheKey,
         wasm: true,
       })
     }
@@ -1241,10 +1449,32 @@
       toggleNativeLog: toggleNativeLog,
       addNativeLogListener: addNativeLogListener,
       DEFAULT_WASM_MODEL_SIZE_LIMIT_BYTES: 1500 * MIB,
+      MAX_WASM_THREADS: MAX_WASM_THREADS,
+      WASM_CONFIG_PATHS: WASM_CONFIG_PATHS,
     }
 
     api.default = api
 
     return api
-  },
-)
+  }
+
+const api = createWhisperNodeApi(root)
+
+export const WhisperContext = api.WhisperContext
+export const WhisperVadContext = api.WhisperVadContext
+export const DEFAULT_WASM_MODEL_SIZE_LIMIT_BYTES =
+  api.DEFAULT_WASM_MODEL_SIZE_LIMIT_BYTES
+export const MAX_WASM_THREADS = api.MAX_WASM_THREADS
+export const configureWasm = api.configureWasm
+export const loadWasmModule = api.loadWasmModule
+export const loadWhisperModule = api.loadWhisperModule
+export const initWhisper = api.initWhisper
+export const initWhisperVad = api.initWhisperVad
+export const toggleNativeLog = api.toggleNativeLog
+export const addNativeLogListener = api.addNativeLogListener
+
+if (root) {
+  root.WhisperNodeWasm = api
+}
+
+export default api

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@fugood/node-whisper-wasm",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "Browser WASM module for whisper.node",
+  "type": "module",
   "main": "index.js",
   "browser": "index.js",
   "types": "index.d.ts",
@@ -39,8 +40,8 @@
     "index.js",
     "index.d.ts",
     "README.md",
-    "whisper-node.js",
     "worker.js",
-    "whisper-node.wasm"
+    "wasm/whisper-node.js",
+    "wasm/whisper-node.wasm"
   ]
-}
+}