@moxxy/plugin-stt-local 0.28.0

package/src/models.ts

@@ -0,0 +1,111 @@
+/**
+ * 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';
+
+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;
+}
+
+const RELEASE_BASE = 'https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models';
+
+function whisperModel(
+  id: WhisperModelId,
+  label: string,
+  sha256: string,
+  approxMb: number,
+): WhisperModelEntry {
+  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: readonly WhisperModelEntry[] = [
+  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: WhisperModelId = 'base';
+
+/** All valid model ids, for error messages and validation. */
+export function modelIds(): string[] {
+  return MODEL_CATALOG.map((m) => m.id);
+}
+
+export function findModel(id: string): WhisperModelEntry | undefined {
+  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: string, field: string): WhisperModelEntry {
+  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;
+}

package/src/platform.test.ts

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  libraryPathVar,
+  resolveSherpaLibDir,
+  sherpaEnv,
+  sherpaPlatformPackage,
+} from './platform.js';
+
+describe('sherpaPlatformPackage', () => {
+  it.each([
+    ['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'],
+  ] as const)('maps %s-%s to %s', (platform, arch, pkg) => {
+    expect(sherpaPlatformPackage(platform as NodeJS.Platform, arch)).toBe(pkg);
+  });
+
+  it('returns null for an unsupported platform/arch', () => {
+    expect(sherpaPlatformPackage('linux', 'ia32')).toBeNull();
+    expect(sherpaPlatformPackage('freebsd', 'x64')).toBeNull();
+  });
+});
+
+describe('libraryPathVar', () => {
+  it('picks the platform dynamic-loader var, or null on Windows', () => {
+    expect(libraryPathVar('darwin')).toBe('DYLD_LIBRARY_PATH');
+    expect(libraryPathVar('linux')).toBe('LD_LIBRARY_PATH');
+    expect(libraryPathVar('win32')).toBeNull();
+  });
+});
+
+describe('sherpaEnv', () => {
+  it('sets the loader var to the lib dir when none is present', () => {
+    expect(sherpaEnv('/libs', 'darwin', {})).toEqual({ DYLD_LIBRARY_PATH: '/libs' });
+    expect(sherpaEnv('/libs', 'linux', {})).toEqual({ LD_LIBRARY_PATH: '/libs' });
+  });
+
+  it('prepends the lib dir to an existing loader path', () => {
+    expect(sherpaEnv('/libs', 'darwin', { DYLD_LIBRARY_PATH: '/other' })).toEqual({
+      DYLD_LIBRARY_PATH: `/libs${path.delimiter}/other`,
+    });
+  });
+
+  it('returns no env on Windows (DLLs resolve next to the addon)', () => {
+    expect(sherpaEnv('C:\\libs', 'win32', {})).toEqual({});
+  });
+});
+
+describe('resolveSherpaLibDir', () => {
+  it('returns the dirname of the resolved platform package.json', () => {
+    const fakeResolve = (req: string): string => {
+      expect(req).toBe('sherpa-onnx-darwin-arm64/package.json');
+      return '/store/sherpa-onnx-darwin-arm64/package.json';
+    };
+    expect(resolveSherpaLibDir('darwin', 'arm64', fakeResolve)).toBe('/store/sherpa-onnx-darwin-arm64');
+  });
+
+  it('returns null when the platform package cannot be resolved', () => {
+    const throwing = (): string => {
+      throw new Error('MODULE_NOT_FOUND');
+    };
+    expect(resolveSherpaLibDir('darwin', 'arm64', throwing)).toBeNull();
+  });
+
+  it('returns null for an unsupported platform without calling resolve', () => {
+    let called = false;
+    const spy = (): string => {
+      called = true;
+      return 'x';
+    };
+    expect(resolveSherpaLibDir('sunos' as NodeJS.Platform, 'x64', spy)).toBeNull();
+    expect(called).toBe(false);
+  });
+});

package/src/platform.ts

@@ -0,0 +1,109 @@
+/**
+ * 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: Readonly<Record<string, string>> = {
+  '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: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): string | null {
+  return PLATFORM_PACKAGES[`${platform}-${arch}`] ?? null;
+}
+
+/** A `require.resolve`-shaped function (injectable for tests). */
+export type ResolveLike = (request: string) => string;
+
+/**
+ * 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: ResolveLike | null | undefined;
+function sherpaAnchoredResolve(): ResolveLike | null {
+  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: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+  resolve?: ResolveLike,
+): string | null {
+  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: NodeJS.Platform = process.platform): string | null {
+  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: string,
+  platform: NodeJS.Platform = process.platform,
+  existing: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const varName = libraryPathVar(platform);
+  if (!varName) return {};
+  const prev = existing[varName];
+  const value = prev ? `${libDir}${path.delimiter}${prev}` : libDir;
+  return { [varName]: value };
+}

package/src/sidecar.ts

@@ -0,0 +1,97 @@
+#!/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,
+  type HostReply,
+  type HostRequest,
+  type SherpaModule,
+} 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(): SherpaModule {
+  return require('sherpa-onnx-node') as SherpaModule;
+}
+
+function send(reply: HostReply): void {
+  // `process.send` is defined only when spawned with an IPC channel (our fork).
+  process.send?.(reply);
+}
+
+function isRequest(msg: unknown): msg is HostRequest {
+  return (
+    typeof msg === 'object' &&
+    msg !== null &&
+    (msg as { type?: unknown }).type === 'transcribe' &&
+    typeof (msg as { id?: unknown }).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(): void {
+  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 as NodeJS.ErrnoException).code === 'ESRCH') process.exit(0);
+      // EPERM ⇒ the process exists but we can't signal it — still alive.
+    }
+  }, 3000);
+  timer.unref?.();
+}
+
+function main(): void {
+  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<void> = Promise.resolve();
+  process.on('message', (msg: unknown) => {
+    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();
+}