@spader/node-whisper-cpp 0.2.2 → 0.5.0

package/dist/audio.d.ts

@@ -0,0 +1,4 @@
+import type { Audio } from "./types.js";
+export declare const SAMPLE_RATE = 16000;
+export declare const fromWav: (data: ArrayBuffer | Uint8Array) => Audio;
+export declare const fromFile: (path: string) => Promise<Audio>;

package/dist/audio.js

@@ -0,0 +1,88 @@
+import { readFile } from "node:fs/promises";
+import { AudioDecodeError } from "./errors.js";
+export const SAMPLE_RATE = 16000;
+const tag = (bytes, offset) => String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+const sampleReader = (view, base, format, bits) => {
+    if (format === 3 && bits === 32)
+        return (i) => view.getFloat32(base + i * 4, true);
+    if (format === 1 || format === 0xfffe) {
+        if (bits === 8)
+            return (i) => (view.getUint8(base + i) - 128) / 128;
+        if (bits === 16)
+            return (i) => view.getInt16(base + i * 2, true) / 32768;
+        if (bits === 24) {
+            return (i) => {
+                const o = base + i * 3;
+                const raw = view.getUint8(o) | (view.getUint8(o + 1) << 8) | (view.getUint8(o + 2) << 16);
+                return (raw & 0x800000 ? raw | ~0xffffff : raw) / 8388608;
+            };
+        }
+        if (bits === 32)
+            return (i) => view.getInt32(base + i * 4, true) / 2147483648;
+    }
+    throw new AudioDecodeError(`unsupported WAV encoding: format ${format}, ${bits}-bit`);
+};
+const decodeWav = (bytes) => {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.byteLength < 12 || tag(bytes, 0) !== "RIFF" || tag(bytes, 8) !== "WAVE") {
+        throw new AudioDecodeError("not a RIFF/WAVE file");
+    }
+    let format = 0;
+    let channels = 0;
+    let sampleRate = 0;
+    let bits = 0;
+    let dataOffset = -1;
+    let dataLength = 0;
+    let offset = 12;
+    while (offset + 8 <= bytes.byteLength) {
+        const id = tag(bytes, offset);
+        const size = view.getUint32(offset + 4, true);
+        const body = offset + 8;
+        if (id === "fmt " && size >= 16 && body + 16 <= bytes.byteLength) {
+            format = view.getUint16(body, true);
+            channels = view.getUint16(body + 2, true);
+            sampleRate = view.getUint32(body + 4, true);
+            bits = view.getUint16(body + 14, true);
+        }
+        else if (id === "data") {
+            dataOffset = body;
+            dataLength = Math.min(size, bytes.byteLength - body);
+        }
+        offset = body + size + (size & 1);
+    }
+    if (dataOffset < 0 || channels === 0 || sampleRate === 0) {
+        throw new AudioDecodeError("missing fmt or data chunk");
+    }
+    const read = sampleReader(view, dataOffset, format, bits);
+    const frames = Math.floor(dataLength / (channels * (bits / 8)));
+    const samples = new Float32Array(frames);
+    for (let i = 0; i < frames; i++) {
+        let sum = 0;
+        for (let c = 0; c < channels; c++)
+            sum += read(i * channels + c);
+        samples[i] = sum / channels;
+    }
+    return { samples, sampleRate, channels };
+};
+const resample = (input, from, to) => {
+    if (from === to)
+        return input;
+    const ratio = from / to;
+    const length = Math.floor(input.length / ratio);
+    const output = new Float32Array(length);
+    for (let i = 0; i < length; i++) {
+        const position = i * ratio;
+        const index = Math.floor(position);
+        const fraction = position - index;
+        const a = input[index] ?? 0;
+        const b = input[index + 1] ?? a;
+        output[i] = a + (b - a) * fraction;
+    }
+    return output;
+};
+export const fromWav = (data) => {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    const decoded = decodeWav(bytes);
+    return resample(decoded.samples, decoded.sampleRate, SAMPLE_RATE);
+};
+export const fromFile = async (path) => fromWav(await readFile(path));

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class ModelLoadError extends Error {
+    constructor(model: string, cause?: unknown);
+}
+export declare class TranscribeError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+export declare class AudioDecodeError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class ModelLoadError extends Error {
+    constructor(model, cause) {
+        super(`failed to load whisper model: ${model}`, { cause });
+        this.name = "ModelLoadError";
+    }
+}
+export class TranscribeError extends Error {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = "TranscribeError";
+    }
+}
+export class AudioDecodeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AudioDecodeError";
+    }
+}

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import type { ContextOptions, Segment, TranscribeOptions } from "./types.js";
-export type { ContextOptions, Segment, TranscribeOptions };
-export * as platform from "./platform.js";
-export declare function version(): string;
-export declare function systemInfo(): string;
-export declare function createContext(options: ContextOptions): Context;
-export declare class Context {
-    private readonly native;
-    constructor(options: ContextOptions);
-    transcribe(options: TranscribeOptions): Promise<Segment[]>;
-    free(): void;
-}
+import * as audio from "./audio.js";
+import * as platform from "./platform.js";
+export type { Audio, Gpu, LoadOptions, Model, ModelInfo, Segment, Session, Token, TranscribeOptions, TranscriptionResult, TranscriptionStream, VadOptions, } from "./types.js";
+export { AudioDecodeError, ModelLoadError, TranscribeError } from "./errors.js";
+export declare const whisper: {
+    load: (options: string | import("./types.js").LoadOptions) => Promise<import("./types.js").Model>;
+    audio: typeof audio;
+    platform: typeof platform;
+    readonly version: string;
+    systemInfo: () => string;
+};
+export default whisper;

package/dist/index.js

@@ -1,23 +1,15 @@
+import * as audio from "./audio.js";
 import { loadAddon } from "./loader.js";
-export * as platform from "./platform.js";
-export function version() {
-    return loadAddon().version();
-}
-export function systemInfo() {
-    return loadAddon().systemInfo();
-}
-export function createContext(options) {
-    return new Context(options);
-}
-export class Context {
-    native;
-    constructor(options) {
-        this.native = new (loadAddon().WhisperContext)(options);
-    }
-    transcribe(options) {
-        return this.native.transcribe(options);
-    }
-    free() {
-        this.native.free();
-    }
-}
+import { load } from "./model.js";
+import * as platform from "./platform.js";
+export { AudioDecodeError, ModelLoadError, TranscribeError } from "./errors.js";
+export const whisper = {
+    load,
+    audio,
+    platform,
+    get version() {
+        return loadAddon().version();
+    },
+    systemInfo: () => loadAddon().systemInfo(),
+};
+export default whisper;

package/dist/loader.js

@@ -14,16 +14,19 @@ function resolvePlatformPackageDir(name) {
         return join(currentDir, "..", "packages", "platform", name.slice(prefix.length));
     }
 }
-let store = {
-    addon: null
-};
-export function loadAddon() {
-    if (store.addon != null)
-        return store.addon;
+function defaultAddonPath() {
     const triple = detect();
     const name = `@spader/node-whisper-cpp-${triple}`;
     const dir = resolvePlatformPackageDir(name);
-    const addonPath = join(dir, "bins", "whisper-addon.node");
-    store.addon = require(addonPath);
-    return store.addon;
+    return join(dir, "bins", "whisper-addon.node");
+}
+const cache = new Map();
+export function loadAddon() {
+    const addonPath = process.env.NODE_WHISPER_CPP_ADDON || defaultAddonPath();
+    const cached = cache.get(addonPath);
+    if (cached)
+        return cached;
+    const addon = require(addonPath);
+    cache.set(addonPath, addon);
+    return addon;
 }

package/dist/model.d.ts

@@ -0,0 +1,2 @@
+import type { LoadOptions, Model } from "./types.js";
+export declare const load: (options: string | LoadOptions) => Promise<Model>;

package/dist/model.js

@@ -0,0 +1,37 @@
+import { ModelLoadError } from "./errors.js";
+import { loadAddon } from "./loader.js";
+import { createSession } from "./session.js";
+import { runStream, runTranscribe } from "./transcribe.js";
+const open = (options) => {
+    const gpu = options.gpu ?? true;
+    try {
+        return new (loadAddon().WhisperContext)({
+            model: options.model,
+            useGpu: gpu !== false,
+            gpuDevice: typeof gpu === "object" ? gpu.device ?? 0 : 0,
+            flashAttn: options.flashAttention ?? false,
+        });
+    }
+    catch (cause) {
+        throw new ModelLoadError(options.model, cause);
+    }
+};
+export const load = async (options) => {
+    const native = open(typeof options === "string" ? { model: options } : options);
+    const info = native.modelInfo();
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        native.free();
+    };
+    return {
+        info,
+        transcribe: (audio, options) => runTranscribe(native, audio, options),
+        transcribeStream: (audio, options) => runStream(native, audio, options),
+        createSession: () => createSession(native.createState()),
+        dispose,
+        [Symbol.dispose]: dispose,
+    };
+};

package/dist/session.d.ts

@@ -0,0 +1,2 @@
+import type { NativeState, Session } from "./types.js";
+export declare const createSession: (native: NativeState) => Session;

package/dist/session.js

@@ -0,0 +1,16 @@
+import { runStream, runTranscribe } from "./transcribe.js";
+export const createSession = (native) => {
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        native.free();
+    };
+    return {
+        transcribe: (audio, options) => runTranscribe(native, audio, options),
+        transcribeStream: (audio, options) => runStream(native, audio, options),
+        dispose,
+        [Symbol.dispose]: dispose,
+    };
+};

package/dist/transcribe.d.ts

@@ -0,0 +1,3 @@
+import type { Audio, NativeState, TranscribeOptions, TranscriptionResult, TranscriptionStream } from "./types.js";
+export declare const runTranscribe: (native: NativeState, audio: Audio, options?: TranscribeOptions) => Promise<TranscriptionResult>;
+export declare const runStream: (native: NativeState, audio: Audio, options?: TranscribeOptions) => TranscriptionStream;

package/dist/transcribe.js

@@ -0,0 +1,118 @@
+import { TranscribeError } from "./errors.js";
+const locks = new WeakMap();
+const withLock = (native, fn) => {
+    const previous = locks.get(native) ?? Promise.resolve();
+    const run = previous.then(fn, fn);
+    locks.set(native, run.then(() => { }, () => { }));
+    return run;
+};
+const makeAbort = (signal) => {
+    if (!signal)
+        return undefined;
+    const flag = new Int32Array(new SharedArrayBuffer(4));
+    if (signal.aborted)
+        Atomics.store(flag, 0, 1);
+    else
+        signal.addEventListener("abort", () => Atomics.store(flag, 0, 1), { once: true });
+    return flag;
+};
+const toNative = (audio, options, onSegment) => {
+    const vad = options.vad;
+    const vadOptions = typeof vad === "object" ? vad : undefined;
+    return {
+        pcm: audio,
+        language: options.language ?? "auto",
+        translate: options.translate,
+        threads: options.threads,
+        prompt: options.prompt,
+        offsetMs: options.offsetMs,
+        durationMs: options.durationMs,
+        maxLen: options.maxLen,
+        splitOnWord: options.splitOnWord,
+        maxTokens: options.maxTokens,
+        tokenTimestamps: options.tokenTimestamps,
+        diarize: options.diarize,
+        temperature: options.temperature,
+        temperatureInc: options.temperatureInc,
+        beamSize: options.beamSize,
+        bestOf: options.bestOf,
+        noSpeechThreshold: options.noSpeechThreshold,
+        entropyThreshold: options.entropyThreshold,
+        logProbThreshold: options.logProbThreshold,
+        suppressBlank: options.suppressBlank,
+        suppressNonSpeech: options.suppressNonSpeech,
+        vad: vad === undefined ? undefined : Boolean(vad),
+        vadModel: vadOptions?.model,
+        vadThreshold: vadOptions?.threshold,
+        vadMinSpeechMs: vadOptions?.minSpeechMs,
+        vadMinSilenceMs: vadOptions?.minSilenceMs,
+        vadMaxSpeechSeconds: vadOptions?.maxSpeechSeconds,
+        vadSpeechPadMs: vadOptions?.speechPadMs,
+        vadSamplesOverlap: vadOptions?.samplesOverlap,
+        abort: makeAbort(options.signal),
+        onProgress: options.onProgress,
+        onSegment,
+    };
+};
+const seconds = (centiseconds) => centiseconds / 100;
+const mapToken = (token) => ({
+    text: token.text,
+    start: seconds(token.t0),
+    end: seconds(token.t1),
+    probability: token.p,
+});
+const mapSegment = (segment) => ({
+    text: segment.text.trim(),
+    start: seconds(segment.t0),
+    end: seconds(segment.t1),
+    noSpeechProb: segment.noSpeechProb,
+    ...(segment.speakerTurn !== undefined && { speakerTurn: segment.speakerTurn }),
+    ...(segment.tokens && { tokens: segment.tokens.map(mapToken) }),
+});
+const mapResult = (result) => {
+    const segments = result.segments.map(mapSegment);
+    return {
+        text: segments
+            .map((segment) => segment.text)
+            .join(" ")
+            .trim(),
+        language: result.language,
+        segments,
+    };
+};
+const run = (native, audio, options, onSegment) => withLock(native, () => native.transcribe(toNative(audio, options, onSegment)).then(mapResult, (cause) => {
+    if (options.signal?.aborted)
+        throw new DOMException("transcription aborted", "AbortError");
+    throw new TranscribeError(cause instanceof Error ? cause.message : "transcription failed", cause);
+}));
+export const runTranscribe = (native, audio, options = {}) => run(native, audio, options);
+export const runStream = (native, audio, options = {}) => {
+    const queue = [];
+    let wake = null;
+    let finished = false;
+    const signal = () => {
+        wake?.();
+        wake = null;
+    };
+    const result = run(native, audio, options, (segment) => {
+        queue.push(mapSegment(segment));
+        signal();
+    });
+    const done = result.finally(() => {
+        finished = true;
+        signal();
+    });
+    done.catch(() => { });
+    const iterator = async function* () {
+        while (true) {
+            while (queue.length)
+                yield queue.shift();
+            if (finished) {
+                await done;
+                return;
+            }
+            await new Promise((resolve) => (wake = resolve));
+        }
+    };
+    return Object.assign(done, { [Symbol.asyncIterator]: iterator });
+};

package/dist/types.d.ts

@@ -1,26 +1,162 @@
-export interface ContextOptions {
+export type Audio = Float32Array;
+export type Gpu = boolean | {
+    device?: number;
+};
+export type LoadOptions = {
     model: string;
-    use_gpu?: boolean;
-    flash_attn?: boolean;
-    gpu_device?: number;
-}
-export interface Segment {
+    gpu?: Gpu;
+    flashAttention?: boolean;
+};
+export type ModelInfo = {
+    type: string;
+    multilingual: boolean;
+    vocabSize: number;
+    audioContextSize: number;
+    textContextSize: number;
+};
+export type VadOptions = {
+    model: string;
+    threshold?: number;
+    minSpeechMs?: number;
+    minSilenceMs?: number;
+    maxSpeechSeconds?: number;
+    speechPadMs?: number;
+    samplesOverlap?: number;
+};
+export type TranscribeOptions = {
+    language?: string;
+    translate?: boolean;
+    threads?: number;
+    prompt?: string;
+    offsetMs?: number;
+    durationMs?: number;
+    maxLen?: number;
+    splitOnWord?: boolean;
+    maxTokens?: number;
+    tokenTimestamps?: boolean;
+    diarize?: boolean;
+    temperature?: number;
+    temperatureInc?: number;
+    beamSize?: number;
+    bestOf?: number;
+    noSpeechThreshold?: number;
+    entropyThreshold?: number;
+    logProbThreshold?: number;
+    suppressBlank?: boolean;
+    suppressNonSpeech?: boolean;
+    vad?: boolean | VadOptions;
+    signal?: AbortSignal;
+    onProgress?: (progress: number) => void;
+};
+export type Token = {
+    text: string;
+    start: number;
+    end: number;
+    probability: number;
+};
+export type Segment = {
+    text: string;
+    start: number;
+    end: number;
+    noSpeechProb: number;
+    speakerTurn?: boolean;
+    tokens?: Token[];
+};
+export type TranscriptionResult = {
+    text: string;
+    language: string;
+    segments: Segment[];
+};
+export type TranscriptionStream = AsyncIterable<Segment> & Promise<TranscriptionResult>;
+export type Session = {
+    transcribe(audio: Audio, options?: TranscribeOptions): Promise<TranscriptionResult>;
+    transcribeStream(audio: Audio, options?: TranscribeOptions): TranscriptionStream;
+    dispose(): void;
+    [Symbol.dispose](): void;
+};
+export type Model = {
+    readonly info: ModelInfo;
+    transcribe(audio: Audio, options?: TranscribeOptions): Promise<TranscriptionResult>;
+    transcribeStream(audio: Audio, options?: TranscribeOptions): TranscriptionStream;
+    createSession(): Session;
+    dispose(): void;
+    [Symbol.dispose](): void;
+};
+export type NativeToken = {
+    text: string;
     t0: number;
     t1: number;
+    p: number;
+};
+export type NativeSegment = {
     text: string;
-}
-export interface TranscribeOptions {
+    t0: number;
+    t1: number;
+    noSpeechProb: number;
+    speakerTurn?: boolean;
+    tokens?: NativeToken[];
+};
+export type NativeResult = {
+    language: string;
+    segments: NativeSegment[];
+};
+export type NativeTranscribeOptions = {
     pcm: Float32Array;
     language?: string;
+    translate?: boolean;
     threads?: number;
-    onSegment?: (segment: Segment) => void;
-}
-export interface NativeContext {
-    transcribe(options: TranscribeOptions): Promise<Segment[]>;
+    prompt?: string;
+    offsetMs?: number;
+    durationMs?: number;
+    maxLen?: number;
+    splitOnWord?: boolean;
+    maxTokens?: number;
+    tokenTimestamps?: boolean;
+    diarize?: boolean;
+    temperature?: number;
+    temperatureInc?: number;
+    beamSize?: number;
+    bestOf?: number;
+    noSpeechThreshold?: number;
+    entropyThreshold?: number;
+    logProbThreshold?: number;
+    suppressBlank?: boolean;
+    suppressNonSpeech?: boolean;
+    vad?: boolean;
+    vadModel?: string;
+    vadThreshold?: number;
+    vadMinSpeechMs?: number;
+    vadMinSilenceMs?: number;
+    vadMaxSpeechSeconds?: number;
+    vadSpeechPadMs?: number;
+    vadSamplesOverlap?: number;
+    abort?: Int32Array;
+    onSegment?: (segment: NativeSegment) => void;
+    onProgress?: (progress: number) => void;
+};
+export type NativeModelInfo = {
+    type: string;
+    multilingual: boolean;
+    vocabSize: number;
+    audioContextSize: number;
+    textContextSize: number;
+};
+export type NativeContextOptions = {
+    model: string;
+    useGpu: boolean;
+    gpuDevice: number;
+    flashAttn: boolean;
+};
+export type NativeState = {
+    transcribe(options: NativeTranscribeOptions): Promise<NativeResult>;
     free(): void;
-}
-export interface NativeAddon {
-    WhisperContext: new (options: ContextOptions) => NativeContext;
+};
+export type NativeContext = NativeState & {
+    createState(): NativeState;
+    modelInfo(): NativeModelInfo;
+};
+export type NativeAddon = {
+    WhisperContext: new (options: NativeContextOptions) => NativeContext;
     version(): string;
     systemInfo(): string;
-}
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spader/node-whisper-cpp",
-  "version": "0.2.2",
+  "version": "0.5.0",
   "type": "module",
   "packageManager": "bun@1.3.9",
   "main": "./dist/index.js",
@@ -25,16 +25,25 @@
   ],
   "scripts": {
     "build": "bun run ./tools/build.ts all",
-    "smoke": "NODE_WHISPER_CPP_BACKEND=cpu bun run ./tools/build.ts all && bun run test",
-    "smoke:cpu": "NODE_WHISPER_CPP_BACKEND=cpu bun run ./tools/build.ts all --ci && bun run test",
-    "test": "bun test ./test/smoke.test.ts",
+    "act:build": "bun run ./tools/act.ts build",
+    "model": "bun run ./tools/model.ts",
+    "fixtures:audio": "bun run ./test/utils/audio-fixtures.ts",
+    "smoke": "NODE_WHISPER_CPP_BACKEND=cpu bun run ./tools/build.ts all --ci && bun run test:integration && bun run test:smoke",
+    "test": "bun test ./test/unit",
+    "test:unit": "bun test ./test/unit",
+    "test:integration": "bun test ./test/integration",
+    "test:smoke": "NODE_WHISPER_CPP_BACKEND=cpu bun test ./test/smoke",
+    "example:basic": "bun run ./example/basic.ts",
+    "example:streaming": "bun run ./example/streaming.ts",
+    "example:concurrent": "bun run ./example/concurrent.ts",
+    "example:kitchen-sink": "bun run ./example/kitchen-sink.ts",
     "clean": "bun run ./tools/clean.ts"
   },
   "optionalDependencies": {
-    "@spader/node-whisper-cpp-arm64-darwin-metal": "0.2.2",
-    "@spader/node-whisper-cpp-arm64-darwin-cpu": "0.2.2",
-    "@spader/node-whisper-cpp-x64-linux-cpu-gnu": "0.2.2",
-    "@spader/node-whisper-cpp-x64-linux-cuda-gnu": "0.2.2"
+    "@spader/node-whisper-cpp-arm64-darwin-metal": "0.5.0",
+    "@spader/node-whisper-cpp-arm64-darwin-cpu": "0.5.0",
+    "@spader/node-whisper-cpp-x64-linux-cpu-gnu": "0.5.0",
+    "@spader/node-whisper-cpp-x64-linux-cuda-gnu": "0.5.0"
   },
   "repository": {
     "type": "git",
@@ -47,6 +56,8 @@
     "node-addon-api": "^8.3.1"
   },
   "devDependencies": {
+    "@actions/core": "^1.11.1",
+    "@actions/exec": "^1.1.1",
     "@clack/prompts": "^1.0.0",
     "@types/bun": "^1.2.21",
     "@types/node": "^24.3.0",