@fugood/node-whisper-wasm 1.0.19 → 1.0.21

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,
 })
@@ -20,21 +24,38 @@ console.log(await promise)
 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
+The package ships both single-thread and pthread WASM artifacts. On
+cross-origin isolated pages with `SharedArrayBuffer`, the loader uses the
+pthread artifact; otherwise it falls back to the single-thread artifact
+automatically. Whisper transcription defaults to up to 8 threads based on
+browser hardware concurrency when pthreads are available; pass `maxThreads` to
+override it. Browser WASM clamps `maxThreads` to the compiled pool limit of 8,
+or 1 in the single-thread fallback. 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, `configureWasm({ threads: false })` to force the
+single-thread artifact, 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`, `wasm/whisper-node.wasm`,
+`wasm/whisper-node.threads.js`, and `wasm/whisper-node.threads.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`.
+embedded into each generated JS file. 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`. Use `npm run build-wasm-docker` to build through Docker; it
+selects a native arm64 Emscripten image on Apple Silicon hosts.

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,19 @@ export interface Module {
 export interface WasmRuntimeOptions {
   worker?: boolean
   workerUrl?: string
+  workerPath?: string
   indexScriptUrl?: string
   scriptUrl?: string
   runtimeScriptUrl?: string
+  jsPath?: string
+  wasmPath?: string
+  threads?: boolean
   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,8 +162,18 @@ 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
+  threadsJs: string
+  threadsWasm: string
+  worker: string
+}
 
 export declare function configureWasm(options: WasmRuntimeOptions): void
+export declare function isWasmThreadsSupported(): boolean
 export declare function loadWasmModule(): Promise<unknown>
 export declare function loadWhisperModule(): Promise<Module>
 export declare function initWhisper(
@@ -177,7 +200,10 @@ declare const _default: {
   initWhisperVad: typeof initWhisperVad
   toggleNativeLog: typeof toggleNativeLog
   addNativeLogListener: typeof addNativeLogListener
+  isWasmThreadsSupported: typeof isWasmThreadsSupported
   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