@moxxy/plugin-stt-local 0.28.0

package/src/live.test.ts

@@ -0,0 +1,80 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createLocalWhisperTranscriber } from './local-stt.js';
+
+// vitest runs the TypeScript SOURCE, so `import.meta.url` here is src/. The
+// sidecar must be the COMPILED entry, so point at dist/sidecar.js (build first:
+// `pnpm -F @moxxy/plugin-stt-local build`).
+const SIDECAR_PATH = fileURLToPath(new URL('../dist/sidecar.js', import.meta.url));
+
+/**
+ * Opt-in end-to-end test that REALLY downloads the tiny Whisper model and runs
+ * the native sherpa sidecar — off by default (it fetches ~111 MB and needs the
+ * platform binary). Run manually with:
+ *
+ *   MOXXY_STT_LOCAL_LIVE=1 pnpm -F @moxxy/plugin-stt-local test
+ */
+const LIVE = !!process.env.MOXXY_STT_LOCAL_LIVE;
+
+/** Generate a 1-second 16 kHz mono PCM16 WAV of a 440 Hz tone as a fixture. The
+ *  transcript of a pure tone is meaningless — the assertion is that the whole
+ *  download → decode → recognize pipeline runs and yields a string. */
+function toneWav(): Uint8Array {
+  const rate = 16_000;
+  const n = rate; // 1 s
+  const dataSize = n * 2;
+  const buf = new Uint8Array(44 + dataSize);
+  const view = new DataView(buf.buffer);
+  const ascii = (o: number, s: string): void => {
+    for (let i = 0; i < s.length; i += 1) buf[o + i] = s.charCodeAt(i);
+  };
+  ascii(0, 'RIFF');
+  view.setUint32(4, 36 + dataSize, true);
+  ascii(8, 'WAVE');
+  ascii(12, 'fmt ');
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, rate, true);
+  view.setUint32(28, rate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  ascii(36, 'data');
+  view.setUint32(40, dataSize, true);
+  for (let i = 0; i < n; i += 1) {
+    const s = Math.sin((2 * Math.PI * 440 * i) / rate) * 0.3;
+    view.setInt16(44 + i * 2, Math.round(s * 32767), true);
+  }
+  return buf;
+}
+
+let modelsDir: string;
+beforeAll(async () => {
+  if (!LIVE) return;
+  modelsDir = await mkdtemp(path.join(tmpdir(), 'stt-local-live-'));
+});
+afterAll(async () => {
+  if (modelsDir) await rm(modelsDir, { recursive: true, force: true });
+});
+
+describe.skipIf(!LIVE)('local STT (live, real download + native sidecar)', () => {
+  it('downloads the tiny model and transcribes a generated WAV fixture', async () => {
+    const stt = createLocalWhisperTranscriber({
+      model: 'tiny',
+      modelsDir,
+      sidecarPath: SIDECAR_PATH,
+    });
+    try {
+      const out = await stt.transcribe(toneWav(), { mimeType: 'audio/wav' });
+      expect(typeof out.text).toBe('string');
+      expect(out.durationSec).toBeCloseTo(1, 1);
+    } finally {
+      stt.shutdown();
+    }
+  }, 600_000);
+});

package/src/local-stt.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it } from 'vitest';
+
+import { MOXXY_PCM16_24KHZ_MIME } from '@moxxy/sdk';
+import { ensureModel } from '@moxxy/model-fetch';
+
+import {
+  createLocalWhisperTranscriber,
+  type LocalWhisperOptions,
+} from './local-stt.js';
+import { buildLocalSttPlugin, LOCAL_WHISPER_TRANSCRIBER_NAME } from './index.js';
+import type { HostClientLike } from './host-client.js';
+import type { HostRequest, TranscribeResult } from './host-protocol.js';
+
+/** Raw PCM16 mono little-endian bytes (the moxxy mic contract) for N samples. */
+function rawPcm16(n: number, value = 0.3): Uint8Array {
+  const bytes = new Uint8Array(n * 2);
+  const view = new DataView(bytes.buffer);
+  for (let i = 0; i < n; i += 1) view.setInt16(i * 2, Math.round(value * 32767), true);
+  return bytes;
+}
+
+const AUDIO = rawPcm16(240); // 240 @24k → 160 @16k after resample
+
+/** A fake host recording each transcribe request; returns a canned result. */
+function fakeHost(result: TranscribeResult = { text: 'hello world' }): {
+  host: HostClientLike;
+  reqs: Array<Omit<HostRequest, 'id' | 'type'>>;
+  shutdowns: number;
+} {
+  const state = { reqs: [] as Array<Omit<HostRequest, 'id' | 'type'>>, shutdowns: 0 };
+  const host: HostClientLike = {
+    async transcribe(req) {
+      state.reqs.push(req);
+      return result;
+    },
+    shutdown() {
+      state.shutdowns += 1;
+    },
+  };
+  return {
+    host,
+    get reqs() {
+      return state.reqs;
+    },
+    get shutdowns() {
+      return state.shutdowns;
+    },
+  };
+}
+
+/** A fake ensureModel recording the urls it was asked to fetch. */
+function fakeEnsure(): { impl: typeof ensureModel; urls: string[] } {
+  const urls: string[] = [];
+  const impl = (async (opts: Parameters<typeof ensureModel>[0]) => {
+    urls.push(opts.url);
+    return { dir: opts.dir, skipped: false };
+  }) as unknown as typeof ensureModel;
+  return { impl, urls };
+}
+
+function makeTranscriber(
+  over: Partial<LocalWhisperOptions> = {},
+  result?: TranscribeResult,
+): {
+  transcriber: ReturnType<typeof createLocalWhisperTranscriber>;
+  host: ReturnType<typeof fakeHost>;
+  ensure: ReturnType<typeof fakeEnsure>;
+} {
+  const host = fakeHost(result);
+  const ensure = fakeEnsure();
+  const transcriber = createLocalWhisperTranscriber({
+    modelsDir: '/models/stt',
+    ensureModelImpl: ensure.impl,
+    hostFactory: () => host.host,
+    log: () => {},
+    ...over,
+  });
+  return { transcriber, host, ensure };
+}
+
+describe('LocalWhisperTranscriber.transcribe', () => {
+  it('defaults to the base model, decodes raw PCM, and returns the transcript', async () => {
+    const { transcriber, host, ensure } = makeTranscriber();
+    const out = await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(out.text).toBe('hello world');
+    expect(ensure.urls).toEqual([
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-whisper-base.tar.bz2',
+    ]);
+    const req = host.reqs[0]!;
+    expect(req.encoder).toContain('sherpa-onnx-whisper-base/base-encoder.onnx');
+    expect(req.decoder).toContain('base-decoder.onnx');
+    expect(req.tokens).toContain('base-tokens.txt');
+    expect(req.sampleRate).toBe(16_000);
+    expect(req.samples.length).toBe(160); // resampled 24k → 16k
+    expect(req.task).toBe('transcribe');
+    expect(out.durationSec).toBeCloseTo(160 / 16_000, 6);
+  });
+
+  it('selects a configured model (small) and its files', async () => {
+    const { transcriber, host, ensure } = makeTranscriber({ model: 'small' });
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(ensure.urls[0]).toContain('sherpa-onnx-whisper-small.tar.bz2');
+    expect(host.reqs[0]!.encoder).toContain('small-encoder.onnx');
+  });
+
+  it('passes a per-call language hint through to the recognizer', async () => {
+    const { transcriber, host } = makeTranscriber();
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME, language: 'pl' });
+    expect(host.reqs[0]!.language).toBe('pl');
+  });
+
+  it('falls back to the configured default language when no per-call hint is given', async () => {
+    const { transcriber, host } = makeTranscriber({ language: 'en' });
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(host.reqs[0]!.language).toBe('en');
+  });
+
+  it('sends an empty language (auto-detect) when neither is set', async () => {
+    const { transcriber, host } = makeTranscriber();
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(host.reqs[0]!.language).toBe('');
+  });
+
+  it('prefers the language the recognizer detected in the result', async () => {
+    const { transcriber } = makeTranscriber({ language: 'en' }, { text: 'cześć', language: 'pl' });
+    const out = await transcriber.transcribe(AUDIO, {
+      mimeType: MOXXY_PCM16_24KHZ_MIME,
+      language: 'en',
+    });
+    expect(out.language).toBe('pl');
+  });
+
+  it('reports the hint language when the recognizer returns none', async () => {
+    const { transcriber } = makeTranscriber({}, { text: 'x' });
+    const out = await transcriber.transcribe(AUDIO, {
+      mimeType: MOXXY_PCM16_24KHZ_MIME,
+      language: 'de',
+    });
+    expect(out.language).toBe('de');
+  });
+
+  it('downloads the model only once across calls', async () => {
+    const { transcriber, ensure } = makeTranscriber();
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(ensure.urls.length).toBe(1);
+  });
+
+  it('returns empty text for empty/silent audio without touching the model', async () => {
+    const { transcriber, host, ensure } = makeTranscriber();
+    const out = await transcriber.transcribe(new Uint8Array(0), { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(out.text).toBe('');
+    expect(ensure.urls.length).toBe(0);
+    expect(host.reqs.length).toBe(0);
+  });
+
+  it('respects a pre-aborted signal', async () => {
+    const { transcriber } = makeTranscriber();
+    const ac = new AbortController();
+    ac.abort(new Error('stop'));
+    await expect(
+      transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME, signal: ac.signal }),
+    ).rejects.toThrow(/stop/);
+  });
+
+  it('trims whitespace from the transcript', async () => {
+    const { transcriber } = makeTranscriber({}, { text: '  padded  ' });
+    const out = await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(out.text).toBe('padded');
+  });
+
+  it('shutdown tears down the host', async () => {
+    const { transcriber, host } = makeTranscriber();
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    transcriber.shutdown();
+    expect(host.shutdowns).toBe(1);
+  });
+});
+
+describe('constructor validation', () => {
+  it('throws CONFIG_INVALID for an unknown configured model', () => {
+    expect(() => createLocalWhisperTranscriber({ model: 'medium' })).toThrow(
+      /Unknown local Whisper model/,
+    );
+  });
+});
+
+describe('buildLocalSttPlugin', () => {
+  it('registers exactly one transcriber named local-whisper', () => {
+    const plugin = buildLocalSttPlugin();
+    expect(plugin.transcribers).toHaveLength(1);
+    const def = plugin.transcribers![0]!;
+    expect(def.name).toBe(LOCAL_WHISPER_TRANSCRIBER_NAME);
+    expect(def.displayName).toContain('Local Whisper');
+  });
+
+  it('createClient() flows per-activation model config through to routing', async () => {
+    const host = fakeHost();
+    const ensure = fakeEnsure();
+    const plugin = buildLocalSttPlugin({
+      defaults: {
+        modelsDir: '/models/stt',
+        ensureModelImpl: ensure.impl,
+        hostFactory: () => host.host,
+        log: () => {},
+      },
+    });
+    const inst = plugin.transcribers![0]!.createClient({ model: 'small', language: 'pl' });
+    await inst.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(ensure.urls[0]).toContain('sherpa-onnx-whisper-small.tar.bz2');
+    expect(host.reqs[0]!.language).toBe('pl');
+  });
+
+  it('createClient() rejects an unknown model in config at construction', () => {
+    const plugin = buildLocalSttPlugin();
+    expect(() => plugin.transcribers![0]!.createClient({ model: 'bad-id' })).toThrow();
+  });
+
+  it('exposes an onShutdown hook', () => {
+    const plugin = buildLocalSttPlugin();
+    expect(typeof plugin.hooks?.onShutdown).toBe('function');
+  });
+});

package/src/local-stt.ts

@@ -0,0 +1,273 @@
+/**
+ * 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 type { spawn } from 'node:child_process';
+
+import {
+  MoxxyError,
+  type TranscribeOptions,
+  type Transcriber,
+  type TranscriptionResult,
+} from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import {
+  ensureModel,
+  type EnsureModelProgress,
+  type EnsureModelResult,
+  type FetchLike,
+} from '@moxxy/model-fetch';
+
+import { TARGET_SAMPLE_RATE } from './audio.js';
+import { decodeToMono16k } from './decode.js';
+import { HostClient, type HostClientLike } from './host-client.js';
+import { DEFAULT_MODEL_ID, requireModel, type WhisperModelEntry } 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;
+
+/** 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;
+}
+
+/** Process-wide set of live transcribers so the plugin's `onShutdown` hook can
+ *  kill every sidecar it spawned. */
+const ACTIVE_STT = new Set<LocalWhisperTranscriber>();
+
+/** Shut down every live local transcriber (kills their sidecars). */
+export function shutdownLocalStt(): void {
+  for (const t of ACTIVE_STT) t.shutdown();
+  ACTIVE_STT.clear();
+}
+
+export class LocalWhisperTranscriber implements Transcriber {
+  readonly name = LOCAL_WHISPER_TRANSCRIBER_NAME;
+
+  private readonly model: WhisperModelEntry;
+  private readonly defaultLanguage: string;
+  private readonly numThreads: number;
+  private readonly modelsDir: string;
+  private readonly provider: string;
+  private readonly sidecarPath: string | undefined;
+  private readonly ensureModelImpl: typeof ensureModel;
+  private readonly fetchImpl: FetchLike | undefined;
+  private readonly hostFactory: () => HostClientLike;
+  private readonly spawnImpl: typeof spawn | undefined;
+  private readonly log: (msg: string) => void;
+
+  private host: HostClientLike | null = null;
+  /** In-flight model download promise — de-dupes concurrent first-use. */
+  private ensuring: Promise<EnsureModelResult> | null = null;
+
+  constructor(opts: LocalWhisperOptions = {}) {
+    // 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: Uint8Array | ArrayBuffer,
+    opts: TranscribeOptions = {},
+  ): Promise<TranscriptionResult> {
+    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: string;
+      language?: string;
+      durationSec?: number;
+    } = { text: result.text.trim(), durationSec };
+    if (reported) out.language = reported;
+    return out;
+  }
+
+  /** Kill this transcriber's sidecar (if any) and drop registration. */
+  shutdown(): void {
+    this.host?.shutdown();
+    this.host = null;
+    ACTIVE_STT.delete(this);
+  }
+
+  private getHost(): HostClientLike {
+    this.host ??= this.hostFactory();
+    return this.host;
+  }
+
+  /** Resolve on-disk paths for the model, downloading + extracting it once. */
+  private async ensureModelFiles(signal?: AbortSignal): Promise<WhisperModelPaths> {
+    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`). */
+  private makeProgressLogger(): (p: EnsureModelProgress) => void {
+    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. */
+  private defaultHost(): HostClientLike {
+    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: LocalWhisperOptions = {}): LocalWhisperTranscriber {
+  return new LocalWhisperTranscriber(opts);
+}

package/src/models.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_MODEL_ID,
+  MODEL_CATALOG,
+  findModel,
+  modelIds,
+  requireModel,
+} from './models.js';
+
+describe('MODEL_CATALOG', () => {
+  it('pins tiny/base/small multilingual models with their release URLs + hashes', () => {
+    expect(modelIds()).toEqual(['tiny', 'base', 'small']);
+    for (const m of MODEL_CATALOG) {
+      expect(m.url).toBe(
+        `https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-whisper-${m.id}.tar.bz2`,
+      );
+      expect(m.archiveRootDir).toBe(`sherpa-onnx-whisper-${m.id}`);
+      expect(m.encoderFile).toBe(`${m.id}-encoder.onnx`);
+      expect(m.decoderFile).toBe(`${m.id}-decoder.onnx`);
+      expect(m.tokensFile).toBe(`${m.id}-tokens.txt`);
+      // 64-hex sha256, lower-case.
+      expect(m.sha256).toMatch(/^[0-9a-f]{64}$/);
+    }
+  });
+
+  it('records the scout-verified checksums verbatim', () => {
+    expect(findModel('tiny')!.sha256).toBe(
+      'c46116994e539aa165266d96b325252728429c12535eb9d8b6a2b10f129e66b1',
+    );
+    expect(findModel('base')!.sha256).toBe(
+      '911b2083efd7c0dca2ac3b358b75222660dc09fb716d64fbfc417ba6c99ff3de',
+    );
+    expect(findModel('small')!.sha256).toBe(
+      '486a46afbb7ba798507190ffe02fea2dd726049af212e774537efac6afb210a6',
+    );
+  });
+
+  it('defaults to base', () => {
+    expect(DEFAULT_MODEL_ID).toBe('base');
+    expect(findModel(DEFAULT_MODEL_ID)).toBeDefined();
+  });
+});
+
+describe('requireModel', () => {
+  it('returns the catalog entry for a known id', () => {
+    expect(requireModel('small', 'model').id).toBe('small');
+  });
+
+  it('throws CONFIG_INVALID with the valid ids for an unknown model', () => {
+    expect(() => requireModel('medium', 'model')).toThrow(/Unknown local Whisper model/);
+    try {
+      requireModel('medium', 'model');
+    } catch (err) {
+      expect((err as { code?: string }).code).toBe('CONFIG_INVALID');
+      expect((err as { hint?: string }).hint).toContain('tiny, base, small');
+    }
+  });
+});