@moxxy/plugin-stt-local 0.28.0

package/dist/host-client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Parent-side manager for the sherpa sidecar: lazy-spawn on first transcribe,
+ * a correlated request/reply protocol over the fork IPC channel, restart-once
+ * on a crash, and a clean shutdown. The `fork` itself is injectable (a
+ * {@link ForkLike}) so tests drive the whole protocol against a fake child with
+ * no real process.
+ */
+import type { HostRequest, TranscribeResult } from './host-protocol.js';
+/** The minimal child-process surface the client drives — satisfied by a real
+ *  `ChildProcess` and by a test fake. */
+export interface ChildHandle {
+    send(message: unknown): boolean;
+    on(event: 'message', listener: (message: unknown) => void): this;
+    on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    kill(signal?: NodeJS.Signals): boolean;
+}
+/** Fork the sidecar with the given env overrides. Injectable for tests. */
+export type ForkLike = (modulePath: string, env: NodeJS.ProcessEnv) => ChildHandle;
+/** Default fork: advanced serialization (Float32Array round-trip), an IPC
+ *  channel, and inherited std streams so sherpa's own diagnostics reach the
+ *  runner log. `env` already carries the platform loader-path var. */
+export declare const defaultFork: ForkLike;
+export interface HostClientOptions {
+    /** Absolute path to the built sidecar (`dist/sidecar.js`). */
+    readonly hostPath: string;
+    /** Env the child is forked with (platform loader path merged over process.env). */
+    readonly env: NodeJS.ProcessEnv;
+    /** Injected fork (tests). Defaults to {@link defaultFork}. */
+    readonly forkImpl?: ForkLike;
+    /** Per-request deadline. Default 300s (a long clip on a big model on CPU). */
+    readonly requestTimeoutMs?: number;
+    /** Optional diagnostic sink. */
+    readonly log?: (msg: string) => void;
+}
+/** The slice of a host the transcriber depends on — lets tests swap a fake. */
+export interface HostClientLike {
+    transcribe(req: Omit<HostRequest, 'id' | 'type'>): Promise<TranscribeResult>;
+    shutdown(): void;
+}
+/** Raised when the sidecar dies with a request in flight; drives the one retry. */
+export declare class HostCrashError extends Error {
+    constructor(message: string);
+}
+export declare class HostClient implements HostClientLike {
+    private readonly hostPath;
+    private readonly env;
+    private readonly forkImpl;
+    private readonly timeoutMs;
+    private readonly log;
+    private child;
+    private readonly pending;
+    private nextId;
+    private disposed;
+    constructor(opts: HostClientOptions);
+    /** Transcribe, restarting the sidecar ONCE if it crashes mid-request. */
+    transcribe(req: Omit<HostRequest, 'id' | 'type'>): Promise<TranscribeResult>;
+    private send;
+    private ensureChild;
+    private onMessage;
+    private onExit;
+    private onError;
+    /** Resolve/reject one pending request, clearing its timer and map entry. */
+    private settle;
+    private rejectAll;
+    private killChild;
+    /** Kill the sidecar and fail any in-flight requests. Idempotent. */
+    shutdown(): void;
+}
+//# sourceMappingURL=host-client.d.ts.map

package/dist/host-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-client.d.ts","sourceRoot":"","sources":["../src/host-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAa,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEnF;yCACyC;AACzC,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;IAChC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IAChG,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;CACxC;AAED,2EAA2E;AAC3E,MAAM,MAAM,QAAQ,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,WAAW,CAAC;AAEnF;;sEAEsE;AACtE,eAAO,MAAM,WAAW,EAAE,QAMI,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,gCAAgC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7E,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,mFAAmF;AACnF,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAUD,qBAAa,UAAW,YAAW,cAAc;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAE5C,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,iBAAiB;IAQnC,yEAAyE;IACnE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYlF,OAAO,CAAC,IAAI;IAuBZ,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,OAAO;IAKf,4EAA4E;IAC5E,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,SAAS;IAYjB,oEAAoE;IACpE,QAAQ,IAAI,IAAI;CAMjB"}

package/dist/host-client.js

@@ -0,0 +1,156 @@
+/**
+ * Parent-side manager for the sherpa sidecar: lazy-spawn on first transcribe,
+ * a correlated request/reply protocol over the fork IPC channel, restart-once
+ * on a crash, and a clean shutdown. The `fork` itself is injectable (a
+ * {@link ForkLike}) so tests drive the whole protocol against a fake child with
+ * no real process.
+ */
+import { fork } from 'node:child_process';
+/** Default fork: advanced serialization (Float32Array round-trip), an IPC
+ *  channel, and inherited std streams so sherpa's own diagnostics reach the
+ *  runner log. `env` already carries the platform loader-path var. */
+export const defaultFork = (modulePath, env) => fork(modulePath, [], {
+    serialization: 'advanced',
+    env,
+    execArgv: [],
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+});
+/** Raised when the sidecar dies with a request in flight; drives the one retry. */
+export class HostCrashError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HostCrashError';
+    }
+}
+const DEFAULT_TIMEOUT_MS = 300_000;
+export class HostClient {
+    hostPath;
+    env;
+    forkImpl;
+    timeoutMs;
+    log;
+    child = null;
+    pending = new Map();
+    nextId = 1;
+    disposed = false;
+    constructor(opts) {
+        this.hostPath = opts.hostPath;
+        this.env = opts.env;
+        this.forkImpl = opts.forkImpl ?? defaultFork;
+        this.timeoutMs = opts.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.log = opts.log ?? (() => { });
+    }
+    /** Transcribe, restarting the sidecar ONCE if it crashes mid-request. */
+    async transcribe(req) {
+        try {
+            return await this.send(req);
+        }
+        catch (err) {
+            if (err instanceof HostCrashError && !this.disposed) {
+                this.log(`stt-local: sherpa sidecar crashed (${err.message}) — restarting once`);
+                return await this.send(req); // a second crash propagates
+            }
+            throw err;
+        }
+    }
+    send(req) {
+        if (this.disposed)
+            return Promise.reject(new Error('stt-local host is shut down'));
+        const child = this.ensureChild();
+        const id = this.nextId++;
+        const message = { ...req, id, type: 'transcribe' };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                // A hung decode is unrecoverable for this child — reset it so the next
+                // call starts fresh.
+                this.killChild();
+                reject(new Error(`stt-local transcription timed out after ${this.timeoutMs} ms`));
+            }, this.timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+            try {
+                child.send(message);
+            }
+            catch (err) {
+                this.settle(id, () => reject(err instanceof Error ? err : new Error(String(err))));
+            }
+        });
+    }
+    ensureChild() {
+        if (this.child)
+            return this.child;
+        const child = this.forkImpl(this.hostPath, this.env);
+        this.child = child;
+        child.on('message', (msg) => this.onMessage(msg));
+        child.on('exit', (code, signal) => this.onExit(code, signal));
+        child.on('error', (err) => this.onError(err));
+        return child;
+    }
+    onMessage(msg) {
+        const reply = msg;
+        if (!reply || typeof reply !== 'object' || typeof reply.id !== 'number')
+            return;
+        const p = this.pending.get(reply.id);
+        if (!p)
+            return;
+        this.settle(reply.id, () => {
+            if (reply.ok) {
+                p.resolve(reply.language !== undefined ? { text: reply.text, language: reply.language } : { text: reply.text });
+            }
+            else {
+                p.reject(new Error(`stt-local sidecar ${reply.error.kind} error: ${reply.error.message}`));
+            }
+        });
+    }
+    onExit(code, signal) {
+        this.child = null;
+        if (this.pending.size === 0)
+            return;
+        const why = `sidecar exited (code=${code ?? 'null'}, signal=${signal ?? 'null'})`;
+        this.rejectAll(new HostCrashError(why));
+    }
+    onError(err) {
+        this.child = null;
+        this.rejectAll(new HostCrashError(`sidecar spawn/runtime error: ${err.message}`));
+    }
+    /** Resolve/reject one pending request, clearing its timer and map entry. */
+    settle(id, run) {
+        const p = this.pending.get(id);
+        if (!p)
+            return;
+        if (p.timer)
+            clearTimeout(p.timer);
+        this.pending.delete(id);
+        run();
+    }
+    rejectAll(err) {
+        for (const [id, p] of this.pending) {
+            if (p.timer)
+                clearTimeout(p.timer);
+            this.pending.delete(id);
+            p.reject(err);
+        }
+    }
+    killChild() {
+        const child = this.child;
+        this.child = null;
+        if (child) {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    /** Kill the sidecar and fail any in-flight requests. Idempotent. */
+    shutdown() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.rejectAll(new Error('stt-local host shut down'));
+        this.killChild();
+    }
+}
+//# sourceMappingURL=host-client.js.map

package/dist/host-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-client.js","sourceRoot":"","sources":["../src/host-client.ts"],"names":[],"mappings":"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"}

package/dist/host-protocol.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The tiny message protocol spoken between the parent (host-client) and the
+ * forked sherpa sidecar, plus the pure per-message handler the sidecar runs.
+ * Kept free of `node:child_process` so BOTH sides can import it (the parent for
+ * the types, the child for the handler) without dragging fork plumbing into
+ * either bundle.
+ *
+ * Wire shape (over the fork IPC channel, `serialization: 'advanced'` so the
+ * `Float32Array` of samples round-trips intact):
+ *   parent → child:  TranscribeRequest  (carries the decoded 16 kHz mono PCM)
+ *   child  → parent: HostReply          (the transcript text)
+ */
+/** One transcription request. Carries the full model config so the sidecar is
+ *  stateless-per-message except for a recognizer cache keyed by `modelKey`. The
+ *  audio is already decoded to Float32 mono @ 16 kHz by the parent — the sidecar
+ *  only owns the native recognition. */
+export interface TranscribeRequest {
+    readonly id: number;
+    readonly type: 'transcribe';
+    /** Cache key for the loaded recognizer (the absolute encoder path). */
+    readonly modelKey: string;
+    /** Absolute path to the Whisper encoder `.onnx`. */
+    readonly encoder: string;
+    /** Absolute path to the Whisper decoder `.onnx`. */
+    readonly decoder: string;
+    /** Absolute path to `<id>-tokens.txt`. */
+    readonly tokens: string;
+    /** Inference thread count. */
+    readonly numThreads: number;
+    /** Compute provider (`cpu`). */
+    readonly provider: string;
+    /** Best-effort Whisper language tag; empty string ⇒ auto-detect. */
+    readonly language: string;
+    /** Whisper task: `transcribe` (same-language) or `translate` (→ English). */
+    readonly task: string;
+    /** Mono PCM in [-1, 1] at `sampleRate`; structured-cloned intact over IPC. */
+    readonly samples: Float32Array;
+    /** Sample rate of `samples` (16000 — the parent resamples before sending). */
+    readonly sampleRate: number;
+}
+export type HostRequest = TranscribeRequest;
+export type HostErrorKind = 
+/** Recognizer failed to load (bad/absent files, unsupported arch, dlopen). */
+'init'
+/** Decoding itself threw. */
+ | 'runtime';
+export interface TranscribeResult {
+    readonly text: string;
+    /** Whisper's detected language, when the native result reports one. */
+    readonly language?: string;
+}
+export type HostReply = ({
+    readonly id: number;
+    readonly ok: true;
+} & TranscribeResult) | {
+    readonly id: number;
+    readonly ok: false;
+    readonly error: {
+        readonly message: string;
+        readonly kind: HostErrorKind;
+    };
+};
+/** The subset of the sherpa-onnx-node surface the sidecar uses. Declared here
+ *  (rather than leaning on the addon's ambient types) so the handler is
+ *  unit-testable with a fake module and typechecks without the native addon. */
+export interface SherpaOfflineStream {
+    acceptWaveform(args: {
+        sampleRate: number;
+        samples: Float32Array;
+    }): void;
+}
+export interface SherpaOfflineRecognizerResult {
+    readonly text: string;
+    /** Whisper detected-language field on some builds; read defensively. */
+    readonly lang?: string;
+}
+export interface SherpaOfflineRecognizer {
+    createStream(): SherpaOfflineStream;
+    decode(stream: SherpaOfflineStream): void;
+    getResult(stream: SherpaOfflineStream): SherpaOfflineRecognizerResult;
+}
+export interface SherpaModule {
+    OfflineRecognizer: new (config: unknown) => SherpaOfflineRecognizer;
+}
+/** Lazily load the native sherpa module (so a dlopen failure surfaces as a
+ *  classified reply, not a boot crash). */
+export type LoadSherpa = () => SherpaModule;
+export type HostMessageHandler = (req: HostRequest) => Promise<HostReply>;
+/**
+ * Build the sidecar's message handler. Loads the sherpa module on first use and
+ * caches one `OfflineRecognizer` per `modelKey` so repeated calls on the same
+ * model reuse the loaded weights. Every failure becomes a typed `ok:false`
+ * reply — nothing throws out of `handle`.
+ */
+export declare function createMessageHandler(loadSherpa: LoadSherpa): HostMessageHandler;
+//# sourceMappingURL=host-protocol.d.ts.map

package/dist/host-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-protocol.d.ts","sourceRoot":"","sources":["../src/host-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;wCAGwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE5C,MAAM,MAAM,aAAa;AACvB,8EAA8E;AAC5E,MAAM;AACR,6BAA6B;GAC3B,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,SAAS,GACjB,CAAC;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,gBAAgB,CAAC,GAC/D;IACE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;KAAE,CAAC;CAC5E,CAAC;AAEN;;gFAEgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3E;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,IAAI,mBAAmB,CAAC;IACpC,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C,SAAS,CAAC,MAAM,EAAE,mBAAmB,GAAG,6BAA6B,CAAC;CACvE;AAED,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,KAAK,MAAM,EAAE,OAAO,KAAK,uBAAuB,CAAC;CACrE;AAED;2CAC2C;AAC3C,MAAM,MAAM,UAAU,GAAG,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,kBAAkB,CAgD/E"}

package/dist/host-protocol.js

@@ -0,0 +1,70 @@
+/**
+ * The tiny message protocol spoken between the parent (host-client) and the
+ * forked sherpa sidecar, plus the pure per-message handler the sidecar runs.
+ * Kept free of `node:child_process` so BOTH sides can import it (the parent for
+ * the types, the child for the handler) without dragging fork plumbing into
+ * either bundle.
+ *
+ * Wire shape (over the fork IPC channel, `serialization: 'advanced'` so the
+ * `Float32Array` of samples round-trips intact):
+ *   parent → child:  TranscribeRequest  (carries the decoded 16 kHz mono PCM)
+ *   child  → parent: HostReply          (the transcript text)
+ */
+/**
+ * Build the sidecar's message handler. Loads the sherpa module on first use and
+ * caches one `OfflineRecognizer` per `modelKey` so repeated calls on the same
+ * model reuse the loaded weights. Every failure becomes a typed `ok:false`
+ * reply — nothing throws out of `handle`.
+ */
+export function createMessageHandler(loadSherpa) {
+    const cache = new Map();
+    let mod = null;
+    return async function handle(req) {
+        let recognizer = cache.get(req.modelKey);
+        if (!recognizer) {
+            try {
+                mod ??= loadSherpa();
+                recognizer = new mod.OfflineRecognizer({
+                    featConfig: { sampleRate: 16_000, featureDim: 80 },
+                    modelConfig: {
+                        whisper: {
+                            encoder: req.encoder,
+                            decoder: req.decoder,
+                            // `language`/`task` are present in the OfflineWhisperModelConfig
+                            // types but exercised by no upstream example — pass them through
+                            // best-effort (empty language ⇒ Whisper auto-detects anyway).
+                            language: req.language,
+                            task: req.task,
+                        },
+                        tokens: req.tokens,
+                        numThreads: req.numThreads,
+                        provider: req.provider,
+                        debug: false,
+                    },
+                });
+                cache.set(req.modelKey, recognizer);
+            }
+            catch (err) {
+                return { id: req.id, ok: false, error: { message: errMsg(err), kind: 'init' } };
+            }
+        }
+        try {
+            const stream = recognizer.createStream();
+            stream.acceptWaveform({ sampleRate: req.sampleRate, samples: req.samples });
+            recognizer.decode(stream);
+            const result = recognizer.getResult(stream);
+            const text = typeof result?.text === 'string' ? result.text : '';
+            const reply = typeof result?.lang === 'string' && result.lang
+                ? { id: req.id, ok: true, text, language: result.lang }
+                : { id: req.id, ok: true, text };
+            return reply;
+        }
+        catch (err) {
+            return { id: req.id, ok: false, error: { message: errMsg(err), kind: 'runtime' } };
+        }
+    };
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=host-protocol.js.map

package/dist/host-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-protocol.js","sourceRoot":"","sources":["../src/host-protocol.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { type Plugin } from '@moxxy/sdk';
+import { type LocalWhisperOptions } from './local-stt.js';
+export { LocalWhisperTranscriber, createLocalWhisperTranscriber, shutdownLocalStt, LOCAL_WHISPER_TRANSCRIBER_NAME, type LocalWhisperOptions, type WhisperModelPaths, } from './local-stt.js';
+export { MODEL_CATALOG, DEFAULT_MODEL_ID, modelIds, findModel, requireModel, type WhisperModelEntry, type WhisperModelId, } from './models.js';
+export { pcm16ToFloat32, downmixToMono, resampleLinear, parseWav, isRiffWave, TARGET_SAMPLE_RATE, type ParsedWav, } from './audio.js';
+export { decodeToMono16k, type DecodeOptions } from './decode.js';
+export { decodeViaFfmpeg, missingFfmpegError, __resetFfmpegProbeForTest, } from './ffmpeg.js';
+export { HostClient, type HostClientLike, type ForkLike, type ChildHandle } from './host-client.js';
+export { sherpaPlatformPackage, resolveSherpaLibDir, sherpaEnv, libraryPathVar, } from './platform.js';
+export interface BuildLocalSttPluginOptions {
+    /** Build-time defaults / test seams for the transcriber (injected
+     *  `ensureModelImpl`, `hostFactory`, `fetchImpl`, `modelsDir`, `log`, …). */
+    readonly defaults?: LocalWhisperOptions;
+}
+/**
+ * Build the @moxxy/plugin-stt-local plugin. Registers exactly one transcriber,
+ * `local-whisper`, backed by sherpa-onnx Whisper models running in a forked
+ * sidecar. Side-effect free at load: no model is downloaded and no process is
+ * spawned until the first `transcribe`. Per-activation config
+ * (`session.transcribers.setActive('local-whisper', { model, language,
+ * numThreads })`) overrides the build-time defaults.
+ *
+ * Like the OpenAI STT sibling, the plugin does NOT set itself active —
+ * registering it is side-effect free (no auto-adopt in TranscriberRegistry).
+ * The host/user activates it explicitly, so a local-only setup never
+ * surprises anyone with a network call (there isn't one here) and a mixed
+ * setup keeps whatever STT backend was chosen.
+ */
+export declare function buildLocalSttPlugin(opts?: BuildLocalSttPluginOptions): Plugin;
+declare const _default: Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,gBAAgB,EAChB,8BAA8B,EAC9B,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,aAAa,EACb,cAAc,EACd,QAAQ,EACR,UAAU,EACV,kBAAkB,EAClB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,SAAS,EACT,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC;iFAC6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,0BAA+B,GAAG,MAAM,CAgBjF;;AAsBD,wBAAqC"}

package/dist/index.js

@@ -0,0 +1,61 @@
+import { definePlugin, defineTranscriber } from '@moxxy/sdk';
+import { createLocalWhisperTranscriber, LOCAL_WHISPER_TRANSCRIBER_NAME, shutdownLocalStt, } from './local-stt.js';
+export { LocalWhisperTranscriber, createLocalWhisperTranscriber, shutdownLocalStt, LOCAL_WHISPER_TRANSCRIBER_NAME, } from './local-stt.js';
+export { MODEL_CATALOG, DEFAULT_MODEL_ID, modelIds, findModel, requireModel, } from './models.js';
+export { pcm16ToFloat32, downmixToMono, resampleLinear, parseWav, isRiffWave, TARGET_SAMPLE_RATE, } from './audio.js';
+export { decodeToMono16k } from './decode.js';
+export { decodeViaFfmpeg, missingFfmpegError, __resetFfmpegProbeForTest, } from './ffmpeg.js';
+export { HostClient } from './host-client.js';
+export { sherpaPlatformPackage, resolveSherpaLibDir, sherpaEnv, libraryPathVar, } from './platform.js';
+/**
+ * Build the @moxxy/plugin-stt-local plugin. Registers exactly one transcriber,
+ * `local-whisper`, backed by sherpa-onnx Whisper models running in a forked
+ * sidecar. Side-effect free at load: no model is downloaded and no process is
+ * spawned until the first `transcribe`. Per-activation config
+ * (`session.transcribers.setActive('local-whisper', { model, language,
+ * numThreads })`) overrides the build-time defaults.
+ *
+ * Like the OpenAI STT sibling, the plugin does NOT set itself active —
+ * registering it is side-effect free (no auto-adopt in TranscriberRegistry).
+ * The host/user activates it explicitly, so a local-only setup never
+ * surprises anyone with a network call (there isn't one here) and a mixed
+ * setup keeps whatever STT backend was chosen.
+ */
+export function buildLocalSttPlugin(opts = {}) {
+    const defaults = opts.defaults ?? {};
+    return definePlugin({
+        name: '@moxxy/plugin-stt-local',
+        version: '0.0.0',
+        transcribers: [
+            defineTranscriber({
+                name: LOCAL_WHISPER_TRANSCRIBER_NAME,
+                displayName: 'Local Whisper (offline, multilingual)',
+                createClient: (config) => createLocalWhisperTranscriber({ ...defaults, ...configToOptions(config) }),
+            }),
+        ],
+        // Kill every spawned sidecar when the session/runner shuts down.
+        hooks: { onShutdown: () => shutdownLocalStt() },
+    });
+}
+/** Narrow the untrusted per-activation config into typed options — only the
+ *  known string `model` / `language` / `provider` and a positive-integer
+ *  `numThreads` are honored so a malformed config can't break `createClient` or
+ *  route to a bad model (unknown ids are caught by `requireModel`). */
+function configToOptions(config) {
+    const out = {};
+    if (typeof config.model === 'string' && config.model)
+        out.model = config.model;
+    if (typeof config.language === 'string')
+        out.language = config.language;
+    if (typeof config.provider === 'string' && config.provider)
+        out.provider = config.provider;
+    if (typeof config.numThreads === 'number' &&
+        Number.isInteger(config.numThreads) &&
+        config.numThreads > 0) {
+        out.numThreads = config.numThreads;
+    }
+    return out;
+}
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default buildLocalSttPlugin();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAe,MAAM,YAAY,CAAC;AAE1E,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,EAC9B,gBAAgB,GAEjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,gBAAgB,EAChB,8BAA8B,GAG/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,SAAS,EACT,YAAY,GAGb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,aAAa,EACb,cAAc,EACd,QAAQ,EACR,UAAU,EACV,kBAAkB,GAEnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAsB,MAAM,aAAa,CAAC;AAClE,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAwD,MAAM,kBAAkB,CAAC;AACpG,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,SAAS,EACT,cAAc,GACf,MAAM,eAAe,CAAC;AAQvB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmC,EAAE;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACrC,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE;YACZ,iBAAiB,CAAC;gBAChB,IAAI,EAAE,8BAA8B;gBACpC,WAAW,EAAE,uCAAuC;gBACpD,YAAY,EAAE,CAAC,MAA+B,EAAE,EAAE,CAChD,6BAA6B,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;aAC7E,CAAC;SACH;QACD,iEAAiE;QACjE,KAAK,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,EAAE;KAChD,CAAC,CAAC;AACL,CAAC;AAED;;;uEAGuE;AACvE,SAAS,eAAe,CAAC,MAA+B;IACtD,MAAM,GAAG,GAA4E,EAAE,CAAC;IACxF,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK;QAAE,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC/E,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;QAAE,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACxE,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ;QAAE,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC3F,IACE,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ;QACrC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC;QACnC,MAAM,CAAC,UAAU,GAAG,CAAC,EACrB,CAAC;QACD,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACrC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,0EAA0E;AAC1E,eAAe,mBAAmB,EAAE,CAAC"}

package/dist/local-stt.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The `local-whisper` Transcriber: fully local, on-device speech-to-text.
+ *
+ * On the first transcription for a model it downloads + verifies that model's
+ * Whisper export (once, via @moxxy/model-fetch), then decodes the inbound audio
+ * to Float32 mono @ 16 kHz IN-PROCESS (raw PCM / WAV) or via ffmpeg (compressed
+ * containers) and hands the samples to the sherpa sidecar ({@link HostClient}).
+ * No key, no network at transcription time.
+ *
+ * Every collaborator is injectable (`ensureModelImpl`, `hostFactory`, `log`,
+ * `modelsDir`, `fetchImpl`, `spawnImpl`) so the whole flow is unit-testable
+ * without the native addon, a real download, or ffmpeg.
+ */
+import type { spawn } from 'node:child_process';
+import { type TranscribeOptions, type Transcriber, type TranscriptionResult } from '@moxxy/sdk';
+import { ensureModel, type FetchLike } from '@moxxy/model-fetch';
+import { type HostClientLike } from './host-client.js';
+/** The single registered transcriber name. */
+export declare const LOCAL_WHISPER_TRANSCRIBER_NAME = "local-whisper";
+/** Resolved on-disk paths sherpa needs for one model. */
+export interface WhisperModelPaths {
+    readonly encoder: string;
+    readonly decoder: string;
+    readonly tokens: string;
+}
+export interface LocalWhisperOptions {
+    /** Model id: `tiny` | `base` | `small`. Default `base` (`small` for Polish). */
+    readonly model?: string;
+    /** Default Whisper language tag (BCP-47-ish, e.g. `en`, `pl`). Per-call
+     *  `TranscribeOptions.language` overrides it; omit to let Whisper auto-detect. */
+    readonly language?: string;
+    /** Inference threads. Default 2. */
+    readonly numThreads?: number;
+    /** Root for downloaded models. Default `~/.moxxy/models/stt` (MOXXY_HOME-aware). */
+    readonly modelsDir?: string;
+    /** sherpa compute provider. Default `cpu`. */
+    readonly provider?: string;
+    /** Absolute path to the built sidecar entry. Default: `sidecar.js` beside
+     *  this module (i.e. `dist/sidecar.js` in a published build). */
+    readonly sidecarPath?: string;
+    /** Injected model-ensure (tests). Defaults to @moxxy/model-fetch `ensureModel`. */
+    readonly ensureModelImpl?: typeof ensureModel;
+    /** Injected `fetch`, threaded into `ensureModel` (tests). */
+    readonly fetchImpl?: FetchLike;
+    /** Injected sidecar host factory (tests). Defaults to a real {@link HostClient}. */
+    readonly hostFactory?: () => HostClientLike;
+    /** Injected `spawn` for the ffmpeg decode path (tests). */
+    readonly spawnImpl?: typeof spawn;
+    /** Diagnostic log sink (download progress etc.). Defaults to stderr. */
+    readonly log?: (msg: string) => void;
+}
+/** Shut down every live local transcriber (kills their sidecars). */
+export declare function shutdownLocalStt(): void;
+export declare class LocalWhisperTranscriber implements Transcriber {
+    readonly name = "local-whisper";
+    private readonly model;
+    private readonly defaultLanguage;
+    private readonly numThreads;
+    private readonly modelsDir;
+    private readonly provider;
+    private readonly sidecarPath;
+    private readonly ensureModelImpl;
+    private readonly fetchImpl;
+    private readonly hostFactory;
+    private readonly spawnImpl;
+    private readonly log;
+    private host;
+    /** In-flight model download promise — de-dupes concurrent first-use. */
+    private ensuring;
+    constructor(opts?: LocalWhisperOptions);
+    transcribe(audio: Uint8Array | ArrayBuffer, opts?: TranscribeOptions): Promise<TranscriptionResult>;
+    /** Kill this transcriber's sidecar (if any) and drop registration. */
+    shutdown(): void;
+    private getHost;
+    /** Resolve on-disk paths for the model, downloading + extracting it once. */
+    private ensureModelFiles;
+    /** A progress callback that logs a single start line then ~every-10% ticks,
+     *  and an extraction line — but stays silent when the model is already
+     *  present (ensureModel emits only `done`). */
+    private makeProgressLogger;
+    /** Build a real sidecar-backed host, resolving the platform loader path.
+     *  Fails clearly when no sherpa binary exists for this platform/arch. */
+    private defaultHost;
+}
+export declare function createLocalWhisperTranscriber(opts?: LocalWhisperOptions): LocalWhisperTranscriber;
+//# sourceMappingURL=local-stt.d.ts.map

package/dist/local-stt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-stt.d.ts","sourceRoot":"","sources":["../src/local-stt.ts"],"names":[],"mappings":"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"}