@juspay/neurolink 12.48.2 → 12.49.0

package/dist/voice/whistle/assets.js

@@ -0,0 +1,270 @@
+/**
+ * Whistle assets: the pinned manifest, where the files live, and the
+ * first-use download.
+ *
+ * Three files make up the engine — the Cactus "needle" runtime (an Emscripten
+ * build: `needle.js` + `needle.wasm`) and the Whistle speech model
+ * (`whistle.cact`). They are fetched from pinned Hugging Face revisions on
+ * first use, verified against a SHA-256, and written atomically (temp file +
+ * rename), so an interrupted download never leaves a file that looks complete.
+ *
+ * Both upstream repositories are Apache-2.0.
+ *
+ * @module voice/whistle/assets
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { createReadStream, existsSync, readFileSync } from "node:fs";
+import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { STT_ERROR_CODES } from "../../types/index.js";
+import { logger } from "../../utils/logger.js";
+import { STTError } from "../errors.js";
+const NEEDLE_REVISION = "2ae11323dc000f5e70c49f7403efa6af12ba9e67";
+const WHISTLE_REVISION = "b358ddadd89b7a713b5aa131f23032d3cca1b251";
+/** Pinned files, in the order they are fetched. */
+export const WHISTLE_ASSETS = [
+    {
+        name: "needle.js",
+        url: `https://huggingface.co/Cactus-Compute/needle3/resolve/${NEEDLE_REVISION}/wasm/needle.js`,
+        sha256: "964681b2a5ec3c4db2f06e45a5b60c8981a7d4ab4cac16ef6bf5b1988657a5f1",
+        bytes: 63_072,
+    },
+    {
+        name: "needle.wasm",
+        url: `https://huggingface.co/Cactus-Compute/needle3/resolve/${NEEDLE_REVISION}/wasm/needle.wasm`,
+        sha256: "c43f48e11f302087250d1e406024956781cd2f02595a5e343b3d7ddd5ef707fa",
+        bytes: 923_348,
+    },
+    {
+        name: "whistle.cact",
+        url: `https://huggingface.co/Cactus-Compute/whistle/resolve/${WHISTLE_REVISION}/whistle.cact`,
+        sha256: "b6e02f048568ac5d01a2042556c658061e699acbc0aa2a1439f52f3d461dffeb",
+        bytes: 16_919_407,
+    },
+];
+/** Per-file download deadline; generous because the model is 17 MB. */
+const DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
+/** One in-flight preparation per directory, shared by concurrent callers. */
+const inFlight = new Map();
+/** Directories already verified in this process. */
+const verified = new Map();
+/**
+ * Where Whistle keeps its files: `slice.modelDir` → `NEUROLINK_WHISTLE_DIR` →
+ * `NEUROLINK_MODEL_DIR/whistle` → the copy shipped with the package
+ * (`models/whistle`, when all three files are there) →
+ * `~/.neurolink/models/whistle`, the only one a download ever writes to.
+ */
+export function resolveWhistleDir(slice) {
+    const explicit = slice?.modelDir?.trim() || process.env.NEUROLINK_WHISTLE_DIR?.trim();
+    if (explicit) {
+        return resolve(explicit);
+    }
+    const modelRoot = process.env.NEUROLINK_MODEL_DIR?.trim();
+    if (modelRoot) {
+        return resolve(modelRoot, "whistle");
+    }
+    const bundled = bundledWhistleDir();
+    if (bundled && whistleAssetsPresent(bundled)) {
+        return bundled;
+    }
+    return join(homedir(), ".neurolink", "models", "whistle");
+}
+let bundledDir;
+/**
+ * The package's own `models/whistle`, found by walking up from this module
+ * to the directory holding NeuroLink's `package.json`. Works from the source
+ * tree, from `dist/` and from the single-file bundles, since all of them sit
+ * below the package root; `null` when nothing above looks like the package.
+ */
+export function bundledWhistleDir() {
+    if (bundledDir !== undefined) {
+        return bundledDir;
+    }
+    bundledDir = null;
+    let dir;
+    try {
+        dir = dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return bundledDir;
+    }
+    for (let depth = 0; depth < 8; depth += 1) {
+        const manifest = join(dir, "package.json");
+        if (existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+                if (parsed.name === "@juspay/neurolink") {
+                    bundledDir = join(dir, "models", "whistle");
+                    return bundledDir;
+                }
+            }
+            catch {
+                // Not a manifest we can read; keep walking up.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return bundledDir;
+}
+/**
+ * Whether missing files may be fetched: on unless `slice.autoDownload` is
+ * `false` or `NEUROLINK_WHISTLE_AUTO_DOWNLOAD` is `0` / `false` / `off` / `no`.
+ */
+export function whistleAutoDownloadEnabled(slice) {
+    if (slice?.autoDownload !== undefined) {
+        return slice.autoDownload;
+    }
+    const env = process.env.NEUROLINK_WHISTLE_AUTO_DOWNLOAD?.trim().toLowerCase();
+    return !(env === "0" || env === "false" || env === "off" || env === "no");
+}
+/** Cheap presence check (no hashing): all three files exist in `dir`. */
+export function whistleAssetsPresent(dir) {
+    return WHISTLE_ASSETS.every((asset) => existsSync(join(dir, asset.name)));
+}
+/**
+ * Make sure all three files are in `dir` and match their pinned hashes,
+ * downloading what is missing when allowed. Concurrent calls for the same
+ * directory share one preparation.
+ */
+export function ensureWhistleAssets(dir, autoDownload) {
+    const done = verified.get(dir);
+    if (done) {
+        return Promise.resolve(done);
+    }
+    const pending = inFlight.get(dir);
+    if (pending) {
+        return pending;
+    }
+    const job = prepare(dir, autoDownload)
+        .then((paths) => {
+        verified.set(dir, paths);
+        return paths;
+    })
+        .finally(() => {
+        inFlight.delete(dir);
+    });
+    inFlight.set(dir, job);
+    return job;
+}
+async function prepare(dir, autoDownload) {
+    const missing = [];
+    const corrupt = [];
+    for (const asset of WHISTLE_ASSETS) {
+        const state = await checkFile(join(dir, asset.name), asset);
+        if (state === "missing") {
+            missing.push(asset);
+        }
+        else if (state === "corrupt") {
+            corrupt.push(asset);
+        }
+    }
+    const needed = [...missing, ...corrupt];
+    if (needed.length > 0) {
+        if (!autoDownload) {
+            throw assetsUnavailable(dir, corrupt.length > 0
+                ? `${corrupt.map((a) => a.name).join(", ")} in ${dir} does not match its pinned SHA-256, and automatic download is off`
+                : "automatic download is off (NEUROLINK_WHISTLE_AUTO_DOWNLOAD=0 or autoDownload: false)");
+        }
+        const total = needed.reduce((sum, a) => sum + a.bytes, 0);
+        logger.info(`[whistle] downloading Whistle (${Math.max(1, Math.round(total / 1_000_000))} MB) to ${dir} — first use only`);
+        try {
+            await mkdir(dir, { recursive: true });
+            for (const asset of needed) {
+                await download(asset, dir);
+            }
+        }
+        catch (error) {
+            if (error instanceof STTError) {
+                throw error;
+            }
+            throw assetsUnavailable(dir, `the download failed (${error instanceof Error ? error.message : String(error)})`, error instanceof Error ? error : undefined);
+        }
+    }
+    return {
+        "needle.js": join(dir, "needle.js"),
+        "needle.wasm": join(dir, "needle.wasm"),
+        "whistle.cact": join(dir, "whistle.cact"),
+    };
+}
+async function checkFile(path, asset) {
+    try {
+        const info = await stat(path);
+        if (!info.isFile()) {
+            return "missing";
+        }
+        if (info.size !== asset.bytes) {
+            return "corrupt";
+        }
+    }
+    catch {
+        return "missing";
+    }
+    return (await hashFile(path)) === asset.sha256 ? "ok" : "corrupt";
+}
+function hashFile(path) {
+    return new Promise((resolvePromise, reject) => {
+        const hash = createHash("sha256");
+        createReadStream(path)
+            .on("data", (chunk) => hash.update(chunk))
+            .on("error", reject)
+            .on("end", () => resolvePromise(hash.digest("hex")));
+    });
+}
+async function download(asset, dir) {
+    const response = await fetch(asset.url, {
+        signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+        redirect: "follow",
+    });
+    if (!response.ok) {
+        throw new Error(`${asset.name}: HTTP ${response.status}`);
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    const digest = createHash("sha256").update(body).digest("hex");
+    if (digest !== asset.sha256) {
+        throw new Error(`${asset.name}: SHA-256 mismatch (expected ${asset.sha256}, got ${digest})`);
+    }
+    const target = join(dir, asset.name);
+    const temp = join(dir, `.${asset.name}.${process.pid}.${randomBytes(4).toString("hex")}.part`);
+    try {
+        await writeFile(temp, body);
+        await rename(temp, target);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    logger.debug(`[whistle] ${asset.name} verified and saved to ${target}`);
+}
+/** The friendly "here is exactly what to put where" error. */
+/** The three files, where they go and where they come from — the body of every "unusable" message. */
+export function describeWhistleAssets(dir, reason) {
+    const width = Math.max(...WHISTLE_ASSETS.map((a) => a.name.length));
+    const lines = WHISTLE_ASSETS.map((a) => `  ${join(dir, a.name).padEnd(dir.length + 1 + width)}  ←  ${a.url}`);
+    return (`Whistle (the built-in local speech-to-text engine) needs three files, and ${reason}.\n` +
+        `Place them here:\n${lines.join("\n")}\n` +
+        "Or point NEUROLINK_WHISTLE_DIR (or credentials.stt.whistle.modelDir) at a directory that has them " +
+        "(a full install of @juspay/neurolink ships a copy in its models/whistle directory), " +
+        "or configure a cloud STT provider.");
+}
+function assetsUnavailable(dir, reason, originalError) {
+    return new STTError({
+        code: STT_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+        message: describeWhistleAssets(dir, reason),
+        category: ErrorCategory.CONFIGURATION,
+        severity: ErrorSeverity.HIGH,
+        retriable: false,
+        context: {
+            provider: "whistle",
+            modelDir: dir,
+            files: WHISTLE_ASSETS.map((a) => ({ name: a.name, url: a.url })),
+        },
+        originalError,
+    });
+}

package/dist/voice/whistle/audio.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Audio decoding for the Whistle engine: anything in, 16 kHz mono Float32 out.
+ *
+ * WAV (PCM 8/16/24/32-bit integer or 32/64-bit float, any sample rate and
+ * channel count, including WAVE_FORMAT_EXTENSIBLE) and raw `pcm16` (PCM16LE
+ * mono at `options.sampleRate`, default 16 kHz) are decoded here with no
+ * dependencies. Compressed formats (mp3, m4a, ogg/opus, webm, flac, mp4 …) go
+ * through ffmpeg — `FFMPEG_PATH`, then the optional `ffmpeg-static` package,
+ * then `ffmpeg` on `PATH` — and are refused with a clear error when none of
+ * those exists.
+ *
+ * @module voice/whistle/audio
+ */
+import type { TTSAudioFormat } from "../../types/index.js";
+/** Formats Whistle decodes without any external tool. */
+export declare const WHISTLE_NATIVE_FORMATS: readonly TTSAudioFormat[];
+/** Formats Whistle decodes through ffmpeg when it is available. */
+export declare const WHISTLE_FFMPEG_FORMATS: readonly TTSAudioFormat[];
+/** The engine's fixed input rate. */
+export declare const WHISTLE_SAMPLE_RATE = 16000;
+/**
+ * Decode `audio` to 16 kHz mono Float32 samples in [-1, 1]. `format` is a
+ * hint; a RIFF/WAVE header is recognised whatever it says.
+ */
+export declare function decodeToWhistlePcm(audio: Buffer, format: TTSAudioFormat | undefined, sampleRate: number | undefined): Promise<Float32Array>;
+/** PCM16LE frames (as streamed by microphones and the chunked adapter) → 16 kHz Float32. */
+export declare function decodePcm16(buf: Buffer, sampleRate: number): Float32Array;
+/**
+ * Resample to 16 kHz: a box filter over each output sample's footprint when
+ * downsampling (a cheap anti-alias), linear interpolation when upsampling.
+ */
+export declare function resampleTo16k(input: Float32Array, rate: number): Float32Array;

package/dist/voice/whistle/audio.js

@@ -0,0 +1,267 @@
+/**
+ * Audio decoding for the Whistle engine: anything in, 16 kHz mono Float32 out.
+ *
+ * WAV (PCM 8/16/24/32-bit integer or 32/64-bit float, any sample rate and
+ * channel count, including WAVE_FORMAT_EXTENSIBLE) and raw `pcm16` (PCM16LE
+ * mono at `options.sampleRate`, default 16 kHz) are decoded here with no
+ * dependencies. Compressed formats (mp3, m4a, ogg/opus, webm, flac, mp4 …) go
+ * through ffmpeg — `FFMPEG_PATH`, then the optional `ffmpeg-static` package,
+ * then `ffmpeg` on `PATH` — and are refused with a clear error when none of
+ * those exists.
+ *
+ * @module voice/whistle/audio
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { STT_ERROR_CODES } from "../../types/index.js";
+import { tryImport } from "../../utils/tryImport.js";
+import { STTError } from "../errors.js";
+/** Formats Whistle decodes without any external tool. */
+export const WHISTLE_NATIVE_FORMATS = [
+    "wav",
+    "pcm16",
+];
+/** Formats Whistle decodes through ffmpeg when it is available. */
+export const WHISTLE_FFMPEG_FORMATS = [
+    "mp3",
+    "m4a",
+    "mp4",
+    "ogg",
+    "opus",
+    "webm",
+    "flac",
+    "mpeg",
+    "mpga",
+];
+/** The engine's fixed input rate. */
+export const WHISTLE_SAMPLE_RATE = 16_000;
+const FFMPEG_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Decode `audio` to 16 kHz mono Float32 samples in [-1, 1]. `format` is a
+ * hint; a RIFF/WAVE header is recognised whatever it says.
+ */
+export async function decodeToWhistlePcm(audio, format, sampleRate) {
+    if (isWav(audio)) {
+        return decodeWav(audio);
+    }
+    if (format === "pcm16") {
+        return decodePcm16(audio, sampleRate ?? WHISTLE_SAMPLE_RATE);
+    }
+    if (format === "wav") {
+        throw STTError.invalidFormat("wav (no RIFF/WAVE header found)", [...WHISTLE_NATIVE_FORMATS, ...WHISTLE_FFMPEG_FORMATS], "whistle");
+    }
+    return decodeWithFfmpeg(audio, format);
+}
+function isWav(buf) {
+    return (buf.length >= 12 &&
+        buf.toString("ascii", 0, 4) === "RIFF" &&
+        buf.toString("ascii", 8, 12) === "WAVE");
+}
+/** PCM16LE frames (as streamed by microphones and the chunked adapter) → 16 kHz Float32. */
+export function decodePcm16(buf, sampleRate) {
+    const n = buf.length >> 1;
+    const out = new Float32Array(n);
+    for (let i = 0; i < n; i++) {
+        out[i] = buf.readInt16LE(i * 2) / 32768;
+    }
+    return resampleTo16k(out, sampleRate);
+}
+function decodeWav(buf) {
+    let offset = 12;
+    let fmt;
+    let data;
+    while (offset + 8 <= buf.length) {
+        const id = buf.toString("ascii", offset, offset + 4);
+        const size = buf.readUInt32LE(offset + 4);
+        const body = offset + 8;
+        if (id === "fmt " && body + 16 <= buf.length) {
+            let format = buf.readUInt16LE(body);
+            // WAVE_FORMAT_EXTENSIBLE: the real format is the first two bytes of the sub-format GUID.
+            if (format === 0xfffe && size >= 26 && body + 26 <= buf.length) {
+                format = buf.readUInt16LE(body + 24);
+            }
+            fmt = {
+                format,
+                channels: buf.readUInt16LE(body + 2),
+                rate: buf.readUInt32LE(body + 4),
+                bits: buf.readUInt16LE(body + 14),
+            };
+        }
+        else if (id === "data") {
+            // Streamed WAVs leave the size at 0 or 0xFFFFFFFF; read to the end then.
+            const available = buf.length - body;
+            data = {
+                start: body,
+                size: size === 0 || size > available ? available : size,
+            };
+            break;
+        }
+        offset = body + size + (size & 1);
+    }
+    if (!fmt || !data) {
+        throw STTError.invalidFormat("wav (missing fmt or data chunk)", "whistle");
+    }
+    const { format, channels, rate, bits } = fmt;
+    const isFloat = format === 3;
+    if (channels < 1 ||
+        rate < 1 ||
+        !((format === 1 && [8, 16, 24, 32].includes(bits)) ||
+            (isFloat && (bits === 32 || bits === 64)))) {
+        throw STTError.invalidFormat(`wav (format ${format}, ${bits}-bit) — Whistle reads PCM 8/16/24/32-bit and 32/64-bit float WAV`, "whistle");
+    }
+    const bytes = bits / 8;
+    const frameBytes = bytes * channels;
+    const frames = Math.floor(data.size / frameBytes);
+    const mono = new Float32Array(frames);
+    const read = (pos) => {
+        if (isFloat) {
+            return bits === 32 ? buf.readFloatLE(pos) : buf.readDoubleLE(pos);
+        }
+        switch (bits) {
+            case 8:
+                return (buf[pos] - 128) / 128;
+            case 16:
+                return buf.readInt16LE(pos) / 32768;
+            case 24:
+                return buf.readIntLE(pos, 3) / 8388608;
+            default:
+                return buf.readInt32LE(pos) / 2147483648;
+        }
+    };
+    for (let f = 0; f < frames; f++) {
+        const base = data.start + f * frameBytes;
+        let sum = 0;
+        for (let c = 0; c < channels; c++) {
+            sum += read(base + c * bytes);
+        }
+        mono[f] = sum / channels;
+    }
+    return resampleTo16k(mono, rate);
+}
+/**
+ * Resample to 16 kHz: a box filter over each output sample's footprint when
+ * downsampling (a cheap anti-alias), linear interpolation when upsampling.
+ */
+export function resampleTo16k(input, rate) {
+    if (rate === WHISTLE_SAMPLE_RATE || input.length === 0) {
+        return input;
+    }
+    const ratio = rate / WHISTLE_SAMPLE_RATE;
+    const outLength = Math.floor(input.length / ratio);
+    const out = new Float32Array(outLength);
+    if (ratio > 1) {
+        for (let i = 0; i < outLength; i++) {
+            const from = Math.floor(i * ratio);
+            const to = Math.min(input.length, Math.max(from + 1, Math.floor((i + 1) * ratio)));
+            let sum = 0;
+            for (let j = from; j < to; j++) {
+                sum += input[j];
+            }
+            out[i] = sum / (to - from);
+        }
+    }
+    else {
+        for (let i = 0; i < outLength; i++) {
+            const pos = i * ratio;
+            const j = Math.floor(pos);
+            const frac = pos - j;
+            const a = input[j];
+            const b = j + 1 < input.length ? input[j + 1] : a;
+            out[i] = a + (b - a) * frac;
+        }
+    }
+    return out;
+}
+async function resolveFfmpeg() {
+    const fromEnv = process.env.FFMPEG_PATH?.trim();
+    if (fromEnv) {
+        return fromEnv;
+    }
+    try {
+        const mod = await tryImport("ffmpeg-static", "Whistle compressed-audio decoding");
+        if (typeof mod.default === "string" && mod.default.length > 0) {
+            return mod.default;
+        }
+    }
+    catch {
+        // Optional: fall back to a system ffmpeg.
+    }
+    return "ffmpeg";
+}
+function ffmpegUnavailable(format, cause) {
+    return new STTError({
+        code: STT_ERROR_CODES.INVALID_AUDIO_FORMAT,
+        message: `Whistle cannot decode ${format ?? "this"} audio without ffmpeg. It reads WAV ` +
+            "(PCM or float, any rate and channel count) and raw pcm16 by itself; for " +
+            `${WHISTLE_FFMPEG_FORMATS.join(", ")} install ffmpeg (pnpm add ffmpeg-static, ` +
+            "or put ffmpeg on PATH, or set FFMPEG_PATH), or convert the audio to WAV first.",
+        context: {
+            provider: "whistle",
+            format,
+            supportedFormats: [...WHISTLE_NATIVE_FORMATS, ...WHISTLE_FFMPEG_FORMATS],
+        },
+        originalError: cause,
+    });
+}
+async function decodeWithFfmpeg(audio, format) {
+    const binary = await resolveFfmpeg();
+    // A file, not a pipe: MP4/M4A often keep their index at the end, which a pipe cannot seek to.
+    const input = join(tmpdir(), `neurolink-whistle-${randomUUID()}.${format ?? "bin"}`);
+    await writeFile(input, audio);
+    try {
+        const raw = await new Promise((resolvePromise, reject) => {
+            const proc = spawn(binary, [
+                "-nostdin",
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-i",
+                input,
+                "-f",
+                "f32le",
+                "-ac",
+                "1",
+                "-ar",
+                String(WHISTLE_SAMPLE_RATE),
+                "pipe:1",
+            ], { stdio: ["ignore", "pipe", "pipe"] });
+            const out = [];
+            let err = "";
+            const timer = setTimeout(() => proc.kill("SIGKILL"), FFMPEG_TIMEOUT_MS);
+            proc.stdout.on("data", (c) => out.push(c));
+            proc.stderr.on("data", (c) => {
+                err = (err + c.toString("utf8")).slice(-2000);
+            });
+            proc.on("error", (e) => {
+                clearTimeout(timer);
+                reject(e);
+            });
+            proc.on("close", (code) => {
+                clearTimeout(timer);
+                if (code === 0) {
+                    resolvePromise(Buffer.concat(out));
+                }
+                else {
+                    reject(new Error(`ffmpeg exited with code ${code}: ${err.trim()}`));
+                }
+            });
+        });
+        const samples = new Float32Array(raw.length >> 2);
+        for (let i = 0; i < samples.length; i++) {
+            samples[i] = raw.readFloatLE(i * 4);
+        }
+        return samples;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw ffmpegUnavailable(format, error instanceof Error ? error : undefined);
+        }
+        throw STTError.invalidFormat(`${format ?? "unknown"} (ffmpeg could not decode it: ${error instanceof Error ? error.message : String(error)})`, [...WHISTLE_NATIVE_FORMATS, ...WHISTLE_FFMPEG_FORMATS], "whistle");
+    }
+    finally {
+        await rm(input, { force: true }).catch(() => undefined);
+    }
+}

package/dist/voice/whistle/engine.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Main-thread side of the Whistle engine: one warm `worker_threads` Worker
+ * that holds the WASM engine and the model, requests answered in order, and a
+ * fresh worker after a crash.
+ *
+ * The worker is unreferenced while idle, so a warm engine never keeps the
+ * process alive on its own; it is referenced again while a request is open.
+ *
+ * @module voice/whistle/engine
+ */
+import type { WhistleAssetPaths, WhistleEngineOutput, WhistleStreamStep } from "../../types/index.js";
+export declare class WhistleEngine {
+    private readonly paths;
+    private worker;
+    private ready;
+    private nextId;
+    private readonly pending;
+    constructor(paths: WhistleAssetPaths);
+    /** Batch transcription of 16 kHz mono samples; long audio is chunked in the worker. */
+    transcribe(pcm: Float32Array, language: string | null, keywords: string | null, timestamps: boolean): Promise<WhistleEngineOutput>;
+    /** Feed about a second of samples to the engine's native stream. */
+    streamProcess(pcm: Float32Array, language: string | null, keywords: string | null): Promise<WhistleStreamStep>;
+    /** Flush the stream's tail and reset its state. */
+    streamStop(): Promise<WhistleStreamStep>;
+    /** Terminate the worker; the next call starts a new one. */
+    dispose(): Promise<void>;
+    private request;
+    private start;
+    /** Drop a dead worker: reject what it held, and let the next call start a new one. */
+    private crash;
+    private failAll;
+}