@moxxy/plugin-stt-local 0.28.0

package/dist/local-stt.js

@@ -0,0 +1,201 @@
+/**
+ * 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 path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { MoxxyError, } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import { ensureModel, } from '@moxxy/model-fetch';
+import { TARGET_SAMPLE_RATE } from './audio.js';
+import { decodeToMono16k } from './decode.js';
+import { HostClient } from './host-client.js';
+import { DEFAULT_MODEL_ID, requireModel } from './models.js';
+import { resolveSherpaLibDir, sherpaEnv, sherpaPlatformPackage } from './platform.js';
+/** The single registered transcriber name. */
+export const LOCAL_WHISPER_TRANSCRIBER_NAME = 'local-whisper';
+const DEFAULT_NUM_THREADS = 2;
+/** Process-wide set of live transcribers so the plugin's `onShutdown` hook can
+ *  kill every sidecar it spawned. */
+const ACTIVE_STT = new Set();
+/** Shut down every live local transcriber (kills their sidecars). */
+export function shutdownLocalStt() {
+    for (const t of ACTIVE_STT)
+        t.shutdown();
+    ACTIVE_STT.clear();
+}
+export class LocalWhisperTranscriber {
+    name = LOCAL_WHISPER_TRANSCRIBER_NAME;
+    model;
+    defaultLanguage;
+    numThreads;
+    modelsDir;
+    provider;
+    sidecarPath;
+    ensureModelImpl;
+    fetchImpl;
+    hostFactory;
+    spawnImpl;
+    log;
+    host = null;
+    /** In-flight model download promise — de-dupes concurrent first-use. */
+    ensuring = null;
+    constructor(opts = {}) {
+        // Validate the configured model up front so a bad config fails clearly at
+        // construction rather than on the first (possibly channel-triggered) call.
+        this.model = requireModel(opts.model ?? DEFAULT_MODEL_ID, 'model');
+        this.defaultLanguage = typeof opts.language === 'string' ? opts.language.trim() : '';
+        this.numThreads =
+            opts.numThreads && Number.isInteger(opts.numThreads) && opts.numThreads > 0
+                ? opts.numThreads
+                : DEFAULT_NUM_THREADS;
+        this.modelsDir = opts.modelsDir ?? moxxyPath('models', 'stt');
+        this.provider = opts.provider ?? 'cpu';
+        this.sidecarPath = opts.sidecarPath;
+        this.ensureModelImpl = opts.ensureModelImpl ?? ensureModel;
+        this.fetchImpl = opts.fetchImpl;
+        this.hostFactory = opts.hostFactory ?? (() => this.defaultHost());
+        this.spawnImpl = opts.spawnImpl;
+        this.log = opts.log ?? ((msg) => process.stderr.write(`${msg}\n`));
+        ACTIVE_STT.add(this);
+    }
+    async transcribe(audio, opts = {}) {
+        opts.signal?.throwIfAborted();
+        // Decode to the canonical Float32 mono @ 16 kHz sherpa wants. This is where
+        // raw PCM / WAV are handled in-process and compressed audio goes to ffmpeg.
+        const samples = await decodeToMono16k(audio, opts.mimeType, {
+            ...(this.spawnImpl ? { spawnImpl: this.spawnImpl } : {}),
+        });
+        opts.signal?.throwIfAborted();
+        if (samples.length === 0) {
+            return { text: '' };
+        }
+        const paths = await this.ensureModelFiles(opts.signal);
+        opts.signal?.throwIfAborted();
+        const language = ((opts.language ?? this.defaultLanguage) || '').trim();
+        const host = this.getHost();
+        const result = await host.transcribe({
+            modelKey: paths.encoder,
+            encoder: paths.encoder,
+            decoder: paths.decoder,
+            tokens: paths.tokens,
+            numThreads: this.numThreads,
+            provider: this.provider,
+            language,
+            task: 'transcribe',
+            samples,
+            sampleRate: TARGET_SAMPLE_RATE,
+        });
+        const durationSec = samples.length / TARGET_SAMPLE_RATE;
+        // Prefer Whisper's detected language; else the caller/default hint (when
+        // set) so downstream still gets a BCP-47 tag.
+        const reported = result.language ?? (language || undefined);
+        const out = { text: result.text.trim(), durationSec };
+        if (reported)
+            out.language = reported;
+        return out;
+    }
+    /** Kill this transcriber's sidecar (if any) and drop registration. */
+    shutdown() {
+        this.host?.shutdown();
+        this.host = null;
+        ACTIVE_STT.delete(this);
+    }
+    getHost() {
+        this.host ??= this.hostFactory();
+        return this.host;
+    }
+    /** Resolve on-disk paths for the model, downloading + extracting it once. */
+    async ensureModelFiles(signal) {
+        const dir = path.join(this.modelsDir, this.model.id);
+        let inflight = this.ensuring;
+        if (!inflight) {
+            inflight = this.ensureModelImpl({
+                url: this.model.url,
+                sha256: this.model.sha256,
+                dir,
+                ...(this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}),
+                ...(signal ? { signal } : {}),
+                onProgress: this.makeProgressLogger(),
+            });
+            this.ensuring = inflight;
+            // On failure, forget the promise so a later call retries the download.
+            inflight.catch(() => {
+                if (this.ensuring === inflight)
+                    this.ensuring = null;
+            });
+        }
+        await inflight;
+        const root = path.join(dir, this.model.archiveRootDir);
+        return {
+            encoder: path.join(root, this.model.encoderFile),
+            decoder: path.join(root, this.model.decoderFile),
+            tokens: path.join(root, this.model.tokensFile),
+        };
+    }
+    /** 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`). */
+    makeProgressLogger() {
+        let started = false;
+        let extracting = false;
+        let lastPct = -1;
+        return (p) => {
+            if (p.phase === 'downloading') {
+                if (!started) {
+                    started = true;
+                    this.log(`stt-local: first use — downloading Whisper ${this.model.id} (~${this.model.approxMb} MB) to ${this.modelsDir}, one-time`);
+                }
+                if (p.totalBytes > 0) {
+                    const pct = Math.floor((p.receivedBytes / p.totalBytes) * 100);
+                    if (pct >= lastPct + 10) {
+                        lastPct = pct - (pct % 10);
+                        this.log(`stt-local: downloading ${this.model.id} … ${lastPct}%`);
+                    }
+                }
+            }
+            else if (p.phase === 'extracting' && !extracting) {
+                extracting = true;
+                this.log(`stt-local: extracting ${this.model.id} …`);
+            }
+            else if (p.phase === 'done' && started) {
+                this.log(`stt-local: ${this.model.id} ready.`);
+            }
+        };
+    }
+    /** Build a real sidecar-backed host, resolving the platform loader path.
+     *  Fails clearly when no sherpa binary exists for this platform/arch. */
+    defaultHost() {
+        const libDir = resolveSherpaLibDir();
+        if (!libDir) {
+            const pkg = sherpaPlatformPackage();
+            throw new MoxxyError({
+                code: 'PLUGIN_LOAD_FAILED',
+                message: pkg
+                    ? `Local Whisper could not load the sherpa-onnx binary (${pkg}). Reinstall @moxxy/plugin-stt-local so its platform dependency is fetched.`
+                    : `Local Whisper has no sherpa-onnx binary for ${process.platform}-${process.arch}.`,
+                hint: 'Use the OpenAI Whisper backend instead, or run on a supported platform (macOS/Linux/Windows x64, macOS/Linux arm64).',
+                context: { platform: process.platform, arch: process.arch },
+            });
+        }
+        const hostPath = this.sidecarPath ?? path.join(path.dirname(fileURLToPath(import.meta.url)), 'sidecar.js');
+        return new HostClient({
+            hostPath,
+            env: { ...process.env, ...sherpaEnv(libDir) },
+            log: this.log,
+        });
+    }
+}
+export function createLocalWhisperTranscriber(opts = {}) {
+    return new LocalWhisperTranscriber(opts);
+}
+//# sourceMappingURL=local-stt.js.map

package/dist/local-stt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-stt.js","sourceRoot":"","sources":["../src/local-stt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,OAAO,EACL,UAAU,GAIX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,WAAW,GAIZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAA0B,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtF,8CAA8C;AAC9C,MAAM,CAAC,MAAM,8BAA8B,GAAG,eAAe,CAAC;AAE9D,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAoC9B;qCACqC;AACrC,MAAM,UAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;AAEtD,qEAAqE;AACrE,MAAM,UAAU,gBAAgB;IAC9B,KAAK,MAAM,CAAC,IAAI,UAAU;QAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;IACzC,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC;AAED,MAAM,OAAO,uBAAuB;IACzB,IAAI,GAAG,8BAA8B,CAAC;IAE9B,KAAK,CAAoB;IACzB,eAAe,CAAS;IACxB,UAAU,CAAS;IACnB,SAAS,CAAS;IAClB,QAAQ,CAAS;IACjB,WAAW,CAAqB;IAChC,eAAe,CAAqB;IACpC,SAAS,CAAwB;IACjC,WAAW,CAAuB;IAClC,SAAS,CAA2B;IACpC,GAAG,CAAwB;IAEpC,IAAI,GAA0B,IAAI,CAAC;IAC3C,wEAAwE;IAChE,QAAQ,GAAsC,IAAI,CAAC;IAE3D,YAAY,OAA4B,EAAE;QACxC,0EAA0E;QAC1E,2EAA2E;QAC3E,IAAI,CAAC,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,IAAI,gBAAgB,EAAE,OAAO,CAAC,CAAC;QACnE,IAAI,CAAC,eAAe,GAAG,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrF,IAAI,CAAC,UAAU;YACb,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC;gBACzE,CAAC,CAAC,IAAI,CAAC,UAAU;gBACjB,CAAC,CAAC,mBAAmB,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC9D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;QACvC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,WAAW,CAAC;QAC3D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC;QACnE,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,UAAU,CACd,KAA+B,EAC/B,OAA0B,EAAE;QAE5B,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QAE9B,4EAA4E;QAC5E,4EAA4E;QAC5E,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE;YAC1D,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QAE9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACtB,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QAE9B,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACxE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC;YACnC,QAAQ,EAAE,KAAK,CAAC,OAAO;YACvB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ;YACR,IAAI,EAAE,YAAY;YAClB,OAAO;YACP,UAAU,EAAE,kBAAkB;SAC/B,CAAC,CAAC;QAEH,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,kBAAkB,CAAC;QACxD,yEAAyE;QACzE,8CAA8C;QAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,CAAC,QAAQ,IAAI,SAAS,CAAC,CAAC;QAC5D,MAAM,GAAG,GAIL,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,CAAC;QAC9C,IAAI,QAAQ;YAAE,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACtC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,sEAAsE;IACtE,QAAQ;QACN,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAEO,OAAO;QACb,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,6EAA6E;IACrE,KAAK,CAAC,gBAAgB,CAAC,MAAoB;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACrD,IAAI,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC;gBAC9B,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG;gBACnB,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;gBACzB,GAAG;gBACH,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxD,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7B,UAAU,EAAE,IAAI,CAAC,kBAAkB,EAAE;aACtC,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;YACzB,uEAAuE;YACvE,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE;gBAClB,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ;oBAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACvD,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,CAAC;QACf,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACvD,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;YAChD,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;YAChD,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;SAC/C,CAAC;IACJ,CAAC;IAED;;mDAE+C;IACvC,kBAAkB;QACxB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,UAAU,GAAG,KAAK,CAAC;QACvB,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC;QACjB,OAAO,CAAC,CAAC,EAAE,EAAE;YACX,IAAI,CAAC,CAAC,KAAK,KAAK,aAAa,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,GAAG,IAAI,CAAC;oBACf,IAAI,CAAC,GAAG,CACN,8CAA8C,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,WAAW,IAAI,CAAC,SAAS,YAAY,CAC1H,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;oBACrB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC;oBAC/D,IAAI,GAAG,IAAI,OAAO,GAAG,EAAE,EAAE,CAAC;wBACxB,OAAO,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;wBAC3B,IAAI,CAAC,GAAG,CAAC,0BAA0B,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,OAAO,GAAG,CAAC,CAAC;oBACpE,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,IAAI,CAAC,CAAC,KAAK,KAAK,YAAY,IAAI,CAAC,UAAU,EAAE,CAAC;gBACnD,UAAU,GAAG,IAAI,CAAC;gBAClB,IAAI,CAAC,GAAG,CAAC,yBAAyB,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;YACvD,CAAC;iBAAM,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,OAAO,EAAE,CAAC;gBACzC,IAAI,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;YACjD,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;6EACyE;IACjE,WAAW;QACjB,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,GAAG,qBAAqB,EAAE,CAAC;YACpC,MAAM,IAAI,UAAU,CAAC;gBACnB,IAAI,EAAE,oBAAoB;gBAC1B,OAAO,EAAE,GAAG;oBACV,CAAC,CAAC,wDAAwD,GAAG,6EAA6E;oBAC1I,CAAC,CAAC,+CAA+C,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,GAAG;gBACtF,IAAI,EAAE,sHAAsH;gBAC5H,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;aAC5D,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,GACZ,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;QAC5F,OAAO,IAAI,UAAU,CAAC;YACpB,QAAQ;YACR,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,EAAE;YAC7C,GAAG,EAAE,IAAI,CAAC,GAAG;SACd,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,UAAU,6BAA6B,CAAC,OAA4B,EAAE;IAC1E,OAAO,IAAI,uBAAuB,CAAC,IAAI,CAAC,CAAC;AAC3C,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The pinned Whisper model catalog.
+ *
+ * Every model is a multilingual sherpa-onnx Whisper export published as a
+ * `.tar.bz2` under the project's `asr-models` GitHub release. Each `sha256` is
+ * copied VERBATIM from that release's `checksum.txt` (re-verified 2026-07-05) —
+ * so a first-use download is content-addressed and tamper-evident, unlike an
+ * unverified blob fetch. The archive extracts to a single top directory
+ * (`archiveRootDir`) holding `<id>-encoder.onnx`, `<id>-decoder.onnx` (+ int8
+ * variants we don't use) and `<id>-tokens.txt`.
+ *
+ * All three are the MULTILINGUAL models (not the `.en` English-only exports),
+ * so Polish (and any other Whisper language) works — `small` is the accuracy
+ * sweet spot for Polish, `base` the balanced default, `tiny` the fastest.
+ */
+export type WhisperModelId = 'tiny' | 'base' | 'small';
+export interface WhisperModelEntry {
+    /** Stable model id (also the `model` config value). */
+    readonly id: WhisperModelId;
+    /** Human label for UI surfaces / the first-use notice. */
+    readonly label: string;
+    /** Pinned archive URL (sherpa-onnx GitHub `asr-models` release). */
+    readonly url: string;
+    /** Pinned hex sha256 of the archive (from the release checksum.txt). */
+    readonly sha256: string;
+    /** Top directory the archive extracts to (`sherpa-onnx-whisper-<id>`). */
+    readonly archiveRootDir: string;
+    /** Encoder ONNX filename inside `archiveRootDir` (`<id>-encoder.onnx`). */
+    readonly encoderFile: string;
+    /** Decoder ONNX filename inside `archiveRootDir` (`<id>-decoder.onnx`). */
+    readonly decoderFile: string;
+    /** Tokens filename inside `archiveRootDir` (`<id>-tokens.txt`). */
+    readonly tokensFile: string;
+    /** Approximate download size in MB (for the one-time first-use notice). */
+    readonly approxMb: number;
+}
+export declare const MODEL_CATALOG: readonly WhisperModelEntry[];
+/** Default model when the caller doesn't pick one. `base` balances size vs.
+ *  accuracy; `small` is recommended for Polish (see the catalog description). */
+export declare const DEFAULT_MODEL_ID: WhisperModelId;
+/** All valid model ids, for error messages and validation. */
+export declare function modelIds(): string[];
+export declare function findModel(id: string): WhisperModelEntry | undefined;
+/** Resolve a model id to its catalog entry, or throw a clear, actionable error
+ *  listing the valid ids. `field` names where the bad id came from. */
+export declare function requireModel(id: string, field: string): WhisperModelEntry;
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAwBD,eAAO,MAAM,aAAa,EAAE,SAAS,iBAAiB,EAmBrD,CAAC;AAEF;iFACiF;AACjF,eAAO,MAAM,gBAAgB,EAAE,cAAuB,CAAC;AAEvD,8DAA8D;AAC9D,wBAAgB,QAAQ,IAAI,MAAM,EAAE,CAEnC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEnE;AAED;uEACuE;AACvE,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAWzE"}

package/dist/models.js

@@ -0,0 +1,61 @@
+/**
+ * The pinned Whisper model catalog.
+ *
+ * Every model is a multilingual sherpa-onnx Whisper export published as a
+ * `.tar.bz2` under the project's `asr-models` GitHub release. Each `sha256` is
+ * copied VERBATIM from that release's `checksum.txt` (re-verified 2026-07-05) —
+ * so a first-use download is content-addressed and tamper-evident, unlike an
+ * unverified blob fetch. The archive extracts to a single top directory
+ * (`archiveRootDir`) holding `<id>-encoder.onnx`, `<id>-decoder.onnx` (+ int8
+ * variants we don't use) and `<id>-tokens.txt`.
+ *
+ * All three are the MULTILINGUAL models (not the `.en` English-only exports),
+ * so Polish (and any other Whisper language) works — `small` is the accuracy
+ * sweet spot for Polish, `base` the balanced default, `tiny` the fastest.
+ */
+import { MoxxyError } from '@moxxy/sdk';
+const RELEASE_BASE = 'https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models';
+function whisperModel(id, label, sha256, approxMb) {
+    const archiveRootDir = `sherpa-onnx-whisper-${id}`;
+    return {
+        id,
+        label,
+        url: `${RELEASE_BASE}/${archiveRootDir}.tar.bz2`,
+        sha256,
+        archiveRootDir,
+        encoderFile: `${id}-encoder.onnx`,
+        decoderFile: `${id}-decoder.onnx`,
+        tokensFile: `${id}-tokens.txt`,
+        approxMb,
+    };
+}
+export const MODEL_CATALOG = [
+    whisperModel('tiny', 'Whisper tiny (multilingual — fastest, lowest accuracy)', 'c46116994e539aa165266d96b325252728429c12535eb9d8b6a2b10f129e66b1', 111),
+    whisperModel('base', 'Whisper base (multilingual — balanced; default)', '911b2083efd7c0dca2ac3b358b75222660dc09fb716d64fbfc417ba6c99ff3de', 198),
+    whisperModel('small', 'Whisper small (multilingual — best accuracy; recommended for Polish)', '486a46afbb7ba798507190ffe02fea2dd726049af212e774537efac6afb210a6', 610),
+];
+/** Default model when the caller doesn't pick one. `base` balances size vs.
+ *  accuracy; `small` is recommended for Polish (see the catalog description). */
+export const DEFAULT_MODEL_ID = 'base';
+/** All valid model ids, for error messages and validation. */
+export function modelIds() {
+    return MODEL_CATALOG.map((m) => m.id);
+}
+export function findModel(id) {
+    return MODEL_CATALOG.find((m) => m.id === id);
+}
+/** Resolve a model id to its catalog entry, or throw a clear, actionable error
+ *  listing the valid ids. `field` names where the bad id came from. */
+export function requireModel(id, field) {
+    const entry = findModel(id);
+    if (!entry) {
+        throw new MoxxyError({
+            code: 'CONFIG_INVALID',
+            message: `Unknown local Whisper model ${JSON.stringify(id)} (${field}).`,
+            hint: `Valid models: ${modelIds().join(', ')}.`,
+            context: { field, model: id },
+        });
+    }
+    return entry;
+}
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAyBxC,MAAM,YAAY,GAAG,oEAAoE,CAAC;AAE1F,SAAS,YAAY,CACnB,EAAkB,EAClB,KAAa,EACb,MAAc,EACd,QAAgB;IAEhB,MAAM,cAAc,GAAG,uBAAuB,EAAE,EAAE,CAAC;IACnD,OAAO;QACL,EAAE;QACF,KAAK;QACL,GAAG,EAAE,GAAG,YAAY,IAAI,cAAc,UAAU;QAChD,MAAM;QACN,cAAc;QACd,WAAW,EAAE,GAAG,EAAE,eAAe;QACjC,WAAW,EAAE,GAAG,EAAE,eAAe;QACjC,UAAU,EAAE,GAAG,EAAE,aAAa;QAC9B,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAiC;IACzD,YAAY,CACV,MAAM,EACN,wDAAwD,EACxD,kEAAkE,EAClE,GAAG,CACJ;IACD,YAAY,CACV,MAAM,EACN,iDAAiD,EACjD,kEAAkE,EAClE,GAAG,CACJ;IACD,YAAY,CACV,OAAO,EACP,sEAAsE,EACtE,kEAAkE,EAClE,GAAG,CACJ;CACF,CAAC;AAEF;iFACiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAmB,MAAM,CAAC;AAEvD,8DAA8D;AAC9D,MAAM,UAAU,QAAQ;IACtB,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAChD,CAAC;AAED;uEACuE;AACvE,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,KAAa;IACpD,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,+BAA+B,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,KAAK,IAAI;YACxE,IAAI,EAAE,iBAAiB,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC/C,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;SAC9B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/platform.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolve the sherpa-onnx platform binary package and the environment the
+ * sidecar must be spawned with.
+ *
+ * CRITICAL native gotcha (scout-verified): sherpa-onnx-node's addon dlopen's
+ * sibling shared libs (`libonnxruntime.dylib`, `libsherpa-onnx-c-api.dylib`, …)
+ * that live inside the per-platform package dir, and dyld/ld.so read
+ * `DYLD_LIBRARY_PATH` / `LD_LIBRARY_PATH` ONCE at process start. So the addon
+ * only resolves its libs when that env var already points at the platform
+ * package dir when the process launches — which is exactly why the host runs in
+ * a freshly-forked child: the PARENT resolves the dir here and sets the var in
+ * the fork's env. On Windows the DLLs sit next to the `.node`, so no env var is
+ * needed.
+ *
+ * Shared verbatim with @moxxy/plugin-tts-local (deliberately duplicated rather
+ * than cross-imported so neither voice plugin depends on the other).
+ */
+/** The platform binary package name for a host, or null if unsupported. */
+export declare function sherpaPlatformPackage(platform?: NodeJS.Platform, arch?: string): string | null;
+/** A `require.resolve`-shaped function (injectable for tests). */
+export type ResolveLike = (request: string) => string;
+/**
+ * Absolute directory of the resolved platform package (which holds the `.node`
+ * addon and its sibling shared libraries), or null when the package can't be
+ * resolved (unsupported platform, or the optionalDependency didn't install).
+ * `resolve` is injectable for tests; the default is anchored at sherpa-onnx-node.
+ */
+export declare function resolveSherpaLibDir(platform?: NodeJS.Platform, arch?: string, resolve?: ResolveLike): string | null;
+/** The dynamic-loader env var name for a platform, or null on Windows. */
+export declare function libraryPathVar(platform?: NodeJS.Platform): string | null;
+/**
+ * Build the env overrides the sidecar must launch with: the platform loader var
+ * with `libDir` PREPENDED to any existing value. Returns `{}` on Windows (DLLs
+ * resolve next to the addon). `existing` defaults to `process.env`.
+ */
+export declare function sherpaEnv(libDir: string, platform?: NodeJS.Platform, existing?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAeH,2EAA2E;AAC3E,wBAAgB,qBAAqB,CACnC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,IAAI,GAAE,MAAqB,GAC1B,MAAM,GAAG,IAAI,CAEf;AAED,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;AAyBtD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,IAAI,GAAE,MAAqB,EAC3B,OAAO,CAAC,EAAE,WAAW,GACpB,MAAM,GAAG,IAAI,CAUf;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,GAAG,IAAI,CAG1F;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,QAAQ,GAAE,MAAM,CAAC,UAAwB,GACxC,MAAM,CAAC,UAAU,CAMnB"}

package/dist/platform.js

@@ -0,0 +1,96 @@
+/**
+ * Resolve the sherpa-onnx platform binary package and the environment the
+ * sidecar must be spawned with.
+ *
+ * CRITICAL native gotcha (scout-verified): sherpa-onnx-node's addon dlopen's
+ * sibling shared libs (`libonnxruntime.dylib`, `libsherpa-onnx-c-api.dylib`, …)
+ * that live inside the per-platform package dir, and dyld/ld.so read
+ * `DYLD_LIBRARY_PATH` / `LD_LIBRARY_PATH` ONCE at process start. So the addon
+ * only resolves its libs when that env var already points at the platform
+ * package dir when the process launches — which is exactly why the host runs in
+ * a freshly-forked child: the PARENT resolves the dir here and sets the var in
+ * the fork's env. On Windows the DLLs sit next to the `.node`, so no env var is
+ * needed.
+ *
+ * Shared verbatim with @moxxy/plugin-tts-local (deliberately duplicated rather
+ * than cross-imported so neither voice plugin depends on the other).
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+/** `${platform}-${arch}` → npm package that ships the native addon + libs.
+ *  Note the Windows package is `sherpa-onnx-win-x64` (renamed from win32-x64). */
+const PLATFORM_PACKAGES = {
+    'darwin-arm64': 'sherpa-onnx-darwin-arm64',
+    'darwin-x64': 'sherpa-onnx-darwin-x64',
+    'linux-x64': 'sherpa-onnx-linux-x64',
+    'linux-arm64': 'sherpa-onnx-linux-arm64',
+    'win32-x64': 'sherpa-onnx-win-x64',
+};
+/** The platform binary package name for a host, or null if unsupported. */
+export function sherpaPlatformPackage(platform = process.platform, arch = process.arch) {
+    return PLATFORM_PACKAGES[`${platform}-${arch}`] ?? null;
+}
+/**
+ * A `require.resolve` anchored at sherpa-onnx-node itself.
+ *
+ * Load-bearing: sherpa's per-platform binary packages are its OWN
+ * `optionalDependencies`, so under pnpm's strict layout they are visible from
+ * sherpa-onnx-node's `node_modules` but NOT hoisted into this plugin's — a
+ * resolve anchored here would `MODULE_NOT_FOUND`. So we first resolve
+ * sherpa-onnx-node, then resolve the platform package from ITS context. Cached
+ * because it walks two package boundaries.
+ */
+let cachedSherpaResolve;
+function sherpaAnchoredResolve() {
+    if (cachedSherpaResolve !== undefined)
+        return cachedSherpaResolve;
+    try {
+        const pluginRequire = createRequire(import.meta.url);
+        const sherpaPkg = pluginRequire.resolve('sherpa-onnx-node/package.json');
+        cachedSherpaResolve = createRequire(sherpaPkg).resolve;
+    }
+    catch {
+        cachedSherpaResolve = null;
+    }
+    return cachedSherpaResolve;
+}
+/**
+ * Absolute directory of the resolved platform package (which holds the `.node`
+ * addon and its sibling shared libraries), or null when the package can't be
+ * resolved (unsupported platform, or the optionalDependency didn't install).
+ * `resolve` is injectable for tests; the default is anchored at sherpa-onnx-node.
+ */
+export function resolveSherpaLibDir(platform = process.platform, arch = process.arch, resolve) {
+    const pkg = sherpaPlatformPackage(platform, arch);
+    if (!pkg)
+        return null;
+    const r = resolve ?? sherpaAnchoredResolve();
+    if (!r)
+        return null;
+    try {
+        return path.dirname(r(`${pkg}/package.json`));
+    }
+    catch {
+        return null;
+    }
+}
+/** The dynamic-loader env var name for a platform, or null on Windows. */
+export function libraryPathVar(platform = process.platform) {
+    if (platform === 'win32')
+        return null;
+    return platform === 'darwin' ? 'DYLD_LIBRARY_PATH' : 'LD_LIBRARY_PATH';
+}
+/**
+ * Build the env overrides the sidecar must launch with: the platform loader var
+ * with `libDir` PREPENDED to any existing value. Returns `{}` on Windows (DLLs
+ * resolve next to the addon). `existing` defaults to `process.env`.
+ */
+export function sherpaEnv(libDir, platform = process.platform, existing = process.env) {
+    const varName = libraryPathVar(platform);
+    if (!varName)
+        return {};
+    const prev = existing[varName];
+    const value = prev ? `${libDir}${path.delimiter}${prev}` : libDir;
+    return { [varName]: value };
+}
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;kFACkF;AAClF,MAAM,iBAAiB,GAAqC;IAC1D,cAAc,EAAE,0BAA0B;IAC1C,YAAY,EAAE,wBAAwB;IACtC,WAAW,EAAE,uBAAuB;IACpC,aAAa,EAAE,yBAAyB;IACxC,WAAW,EAAE,qBAAqB;CACnC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,UAAU,qBAAqB,CACnC,WAA4B,OAAO,CAAC,QAAQ,EAC5C,OAAe,OAAO,CAAC,IAAI;IAE3B,OAAO,iBAAiB,CAAC,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC,IAAI,IAAI,CAAC;AAC1D,CAAC;AAKD;;;;;;;;;GASG;AACH,IAAI,mBAAmD,CAAC;AACxD,SAAS,qBAAqB;IAC5B,IAAI,mBAAmB,KAAK,SAAS;QAAE,OAAO,mBAAmB,CAAC;IAClE,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;QACzE,mBAAmB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,mBAAmB,GAAG,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,WAA4B,OAAO,CAAC,QAAQ,EAC5C,OAAe,OAAO,CAAC,IAAI,EAC3B,OAAqB;IAErB,MAAM,GAAG,GAAG,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,CAAC,GAAG,OAAO,IAAI,qBAAqB,EAAE,CAAC;IAC7C,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,eAAe,CAAC,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,WAA4B,OAAO,CAAC,QAAQ;IACzE,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,iBAAiB,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,MAAc,EACd,WAA4B,OAAO,CAAC,QAAQ,EAC5C,WAA8B,OAAO,CAAC,GAAG;IAEzC,MAAM,OAAO,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IAClE,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC"}

package/dist/sidecar.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * sherpa-onnx STT sidecar — a forked child that owns the native sherpa addon.
+ *
+ * It exists as a SEPARATE process for one hard reason (see ./platform.ts): the
+ * addon's shared libraries only resolve when `DYLD_LIBRARY_PATH` /
+ * `LD_LIBRARY_PATH` points at the platform package dir AT PROCESS START, so the
+ * parent forks this with that env pre-set. Forking (not `spawn`) gives us a
+ * structured IPC channel; the parent uses `serialization: 'advanced'` so the
+ * `Float32Array` of samples round-trips without manual byte packing.
+ *
+ * Protocol: {@link ./host-protocol.ts}. This module is the thin runtime glue —
+ * lazily `require`ing the native module (a dlopen failure becomes a classified
+ * `init` reply rather than a boot crash), plus lifecycle self-termination so an
+ * orphaned sidecar never lingers.
+ */
+export {};
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../src/sidecar.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}

package/dist/sidecar.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * sherpa-onnx STT sidecar — a forked child that owns the native sherpa addon.
+ *
+ * It exists as a SEPARATE process for one hard reason (see ./platform.ts): the
+ * addon's shared libraries only resolve when `DYLD_LIBRARY_PATH` /
+ * `LD_LIBRARY_PATH` points at the platform package dir AT PROCESS START, so the
+ * parent forks this with that env pre-set. Forking (not `spawn`) gives us a
+ * structured IPC channel; the parent uses `serialization: 'advanced'` so the
+ * `Float32Array` of samples round-trips without manual byte packing.
+ *
+ * Protocol: {@link ./host-protocol.ts}. This module is the thin runtime glue —
+ * lazily `require`ing the native module (a dlopen failure becomes a classified
+ * `init` reply rather than a boot crash), plus lifecycle self-termination so an
+ * orphaned sidecar never lingers.
+ */
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { createMessageHandler, } from './host-protocol.js';
+const require = createRequire(import.meta.url);
+/** Lazy native load — deferred so a missing/broken addon is a caught, reported
+ *  `init` error on the first transcribe, not an unhandled boot exception. */
+function loadSherpa() {
+    return require('sherpa-onnx-node');
+}
+function send(reply) {
+    // `process.send` is defined only when spawned with an IPC channel (our fork).
+    process.send?.(reply);
+}
+function isRequest(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        msg.type === 'transcribe' &&
+        typeof msg.id === 'number');
+}
+/**
+ * Self-terminate if the parent runner disappears. `fork` delivers a
+ * `disconnect` event when the IPC channel closes (parent exit / explicit
+ * disconnect); belt-and-braces, poll the parent PID too — a hard SIGKILL of the
+ * parent may not always close the channel promptly.
+ */
+function armLifecycle() {
+    process.on('disconnect', () => process.exit(0));
+    const parentPid = process.ppid;
+    if (!parentPid || parentPid <= 1)
+        return;
+    const timer = setInterval(() => {
+        try {
+            process.kill(parentPid, 0); // existence probe, no signal delivered
+        }
+        catch (err) {
+            if (err.code === 'ESRCH')
+                process.exit(0);
+            // EPERM ⇒ the process exists but we can't signal it — still alive.
+        }
+    }, 3000);
+    timer.unref?.();
+}
+function main() {
+    const handle = createMessageHandler(loadSherpa);
+    // Serialise requests: sherpa's OfflineRecognizer is not re-entrant, and
+    // processing one at a time keeps memory bounded under a burst of voice notes.
+    let queue = Promise.resolve();
+    process.on('message', (msg) => {
+        if (!isRequest(msg))
+            return;
+        queue = queue
+            .then(async () => {
+            const reply = await handle(msg);
+            send(reply);
+        })
+            .catch((err) => {
+            send({
+                id: msg.id,
+                ok: false,
+                error: { message: err instanceof Error ? err.message : String(err), kind: 'runtime' },
+            });
+        });
+    });
+    armLifecycle();
+}
+// Run only when executed as the forked child, never when imported by a test.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+    main();
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/sidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.js","sourceRoot":"","sources":["../src/sidecar.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EACL,oBAAoB,GAIrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,SAAS,UAAU;IACjB,OAAO,OAAO,CAAC,kBAAkB,CAAiB,CAAC;AACrD,CAAC;AAED,SAAS,IAAI,CAAC,KAAgB;IAC5B,8EAA8E;IAC9E,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACX,GAA0B,CAAC,IAAI,KAAK,YAAY;QACjD,OAAQ,GAAwB,CAAC,EAAE,KAAK,QAAQ,CACjD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY;IACnB,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/B,IAAI,CAAC,SAAS,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO;IACzC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,uCAAuC;QACrE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,OAAO;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACrE,mEAAmE;QACrE,CAAC;IACH,CAAC,EAAE,IAAI,CAAC,CAAC;IACT,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;AAClB,CAAC;AAED,SAAS,IAAI;IACX,MAAM,MAAM,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAChD,wEAAwE;IACxE,8EAA8E;IAC9E,IAAI,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAY,EAAE,EAAE;QACrC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;YAAE,OAAO;QAC5B,KAAK,GAAG,KAAK;aACV,IAAI,CAAC,KAAK,IAAI,EAAE;YACf,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,CAAC,KAAK,CAAC,CAAC;QACd,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;aACtF,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IACH,YAAY,EAAE,CAAC;AACjB,CAAC;AAED,6EAA6E;AAC7E,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,IAAI,EAAE,CAAC;AACT,CAAC"}