@moxxy/plugin-tts-local 0.28.0

package/src/local-tts.ts

@@ -0,0 +1,268 @@
+/**
+ * The `local-piper` Synthesizer: fully local, on-device text-to-speech.
+ *
+ * On the first synthesis for a voice it downloads + verifies that voice's Piper
+ * model (once, via @moxxy/model-fetch), then hands text to the sherpa sidecar
+ * ({@link HostClient}) and wraps the returned samples as WAV. No key, no network
+ * at synthesis time. Language routing sends `pl*` requests to the configured
+ * Polish voice; an explicit `opts.voice` (a catalog id) overrides everything.
+ *
+ * Every collaborator is injectable (`ensureModelImpl`, `hostFactory`, `log`,
+ * `modelsDir`, `fetchImpl`) so the whole flow is unit-testable without the
+ * native addon or a real download.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { MoxxyError, type SynthesizeOptions, type SynthesisResult, type Synthesizer } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import {
+  ensureModel,
+  type EnsureModelProgress,
+  type EnsureModelResult,
+  type FetchLike,
+} from '@moxxy/model-fetch';
+
+import { HostClient, type HostClientLike } from './host-client.js';
+import { resolveSherpaLibDir, sherpaEnv, sherpaPlatformPackage } from './platform.js';
+import {
+  DEFAULT_POLISH_VOICE_ID,
+  DEFAULT_VOICE_ID,
+  requireVoice,
+  routeVoice,
+  type VoiceEntry,
+} from './voices.js';
+import { encodeWav } from './wav.js';
+
+/** The single registered synthesizer name — surfaces show this in `set_voice`. */
+export const LOCAL_PIPER_SYNTHESIZER_NAME = 'local-piper';
+
+/** Local speaking-rate bounds. Piper distorts badly outside this range. */
+const MIN_SPEED = 0.5;
+const MAX_SPEED = 2.0;
+const DEFAULT_NUM_THREADS = 2;
+
+/** Map a `SynthesizeOptions.rate` multiplier onto sherpa's `speed`, clamped.
+ *  An absent / non-finite rate yields 1.0 (natural speed). */
+export function clampSpeed(rate: number | undefined): number {
+  if (rate === undefined || !Number.isFinite(rate)) return 1.0;
+  return Math.min(MAX_SPEED, Math.max(MIN_SPEED, rate));
+}
+
+/** Resolved on-disk paths sherpa needs for one voice. */
+export interface VoiceModelPaths {
+  readonly model: string;
+  readonly tokens: string;
+  readonly dataDir: string;
+}
+
+export interface LocalPiperOptions {
+  /** Default (non-Polish) voice id. Default `en_US-amy-medium`. */
+  readonly voice?: string;
+  /** Voice used for `pl*` language requests. Default `pl_PL-gosia-medium`. */
+  readonly polishVoice?: string;
+  /** Inference threads. Default 2. */
+  readonly numThreads?: number;
+  /** Root for downloaded voices. Default `~/.moxxy/models/tts` (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). Overridable so
+   *  the source-run live test can point at the compiled sidecar. */
+  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;
+  /** Diagnostic log sink (download progress etc.). Defaults to stderr. */
+  readonly log?: (msg: string) => void;
+}
+
+/** Process-wide set of live synthesizers so the plugin's `onShutdown` hook can
+ *  kill every sidecar it spawned. */
+const ACTIVE_SYNTHS = new Set<LocalPiperSynthesizer>();
+
+/** Shut down every live local synthesizer (kills their sidecars). */
+export function shutdownLocalTts(): void {
+  for (const s of ACTIVE_SYNTHS) s.shutdown();
+  ACTIVE_SYNTHS.clear();
+}
+
+export class LocalPiperSynthesizer implements Synthesizer {
+  readonly name = LOCAL_PIPER_SYNTHESIZER_NAME;
+  readonly mimeType = 'audio/wav';
+
+  private readonly voiceId: string;
+  private readonly polishVoiceId: 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 log: (msg: string) => void;
+
+  private host: HostClientLike | null = null;
+  /** In-flight per-voice download promises — de-dupes concurrent first-use. */
+  private readonly ensuring = new Map<string, Promise<EnsureModelResult>>();
+
+  constructor(opts: LocalPiperOptions = {}) {
+    // Validate configured voice ids up front so a bad config fails clearly at
+    // construction rather than on the first (possibly channel-triggered) call.
+    this.voiceId = requireVoice(opts.voice ?? DEFAULT_VOICE_ID, 'voice').id;
+    this.polishVoiceId = requireVoice(opts.polishVoice ?? DEFAULT_POLISH_VOICE_ID, 'polishVoice').id;
+    this.numThreads =
+      opts.numThreads && Number.isInteger(opts.numThreads) && opts.numThreads > 0
+        ? opts.numThreads
+        : DEFAULT_NUM_THREADS;
+    this.modelsDir = opts.modelsDir ?? moxxyPath('models', 'tts');
+    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.log = opts.log ?? ((msg) => process.stderr.write(`${msg}\n`));
+    ACTIVE_SYNTHS.add(this);
+  }
+
+  async synthesize(text: string, opts: SynthesizeOptions = {}): Promise<SynthesisResult> {
+    opts.signal?.throwIfAborted();
+    const voice = routeVoice({
+      ...(opts.voice !== undefined ? { requestedVoice: opts.voice } : {}),
+      ...(opts.language !== undefined ? { language: opts.language } : {}),
+      defaultVoice: this.voiceId,
+      polishVoice: this.polishVoiceId,
+    });
+
+    const paths = await this.ensureVoice(voice, opts.signal);
+    opts.signal?.throwIfAborted();
+
+    const host = this.getHost();
+    const { samples, sampleRate } = await host.synthesize({
+      voiceKey: paths.model,
+      model: paths.model,
+      tokens: paths.tokens,
+      dataDir: paths.dataDir,
+      numThreads: this.numThreads,
+      provider: this.provider,
+      text,
+      sid: 0,
+      speed: clampSpeed(opts.rate),
+    });
+
+    if (!samples || samples.length === 0) {
+      throw new MoxxyError({
+        code: 'INTERNAL',
+        message: 'Local TTS produced no audio samples.',
+        context: { voice: voice.id },
+      });
+    }
+    return { audio: encodeWav(samples, sampleRate), mimeType: this.mimeType };
+  }
+
+  /** Kill this synthesizer's sidecar (if any) and drop registration. */
+  shutdown(): void {
+    this.host?.shutdown();
+    this.host = null;
+    ACTIVE_SYNTHS.delete(this);
+  }
+
+  private getHost(): HostClientLike {
+    this.host ??= this.hostFactory();
+    return this.host;
+  }
+
+  /** Resolve on-disk paths for `voice`, downloading + extracting it once. */
+  private async ensureVoice(voice: VoiceEntry, signal?: AbortSignal): Promise<VoiceModelPaths> {
+    const dir = path.join(this.modelsDir, voice.id);
+    let inflight = this.ensuring.get(voice.id);
+    if (!inflight) {
+      inflight = this.ensureModelImpl({
+        url: voice.url,
+        sha256: voice.sha256,
+        dir,
+        ...(this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}),
+        ...(signal ? { signal } : {}),
+        onProgress: this.makeProgressLogger(voice),
+      });
+      this.ensuring.set(voice.id, inflight);
+      // On failure, forget the promise so a later call retries the download.
+      inflight.catch(() => this.ensuring.delete(voice.id));
+    }
+    await inflight;
+    return this.voicePaths(voice, dir);
+  }
+
+  private voicePaths(voice: VoiceEntry, dir: string): VoiceModelPaths {
+    const root = path.join(dir, voice.archiveRootDir);
+    return {
+      model: path.join(root, voice.modelFile),
+      tokens: path.join(root, 'tokens.txt'),
+      dataDir: path.join(root, 'espeak-ng-data'),
+    };
+  }
+
+  /** A progress callback that logs a single start line then ~every-10% ticks,
+   *  and an extraction line — but stays silent when the voice is already
+   *  present (ensureModel emits only `done`). */
+  private makeProgressLogger(voice: VoiceEntry): (p: EnsureModelProgress) => void {
+    let started = false;
+    let extracting = false;
+    let lastPct = -1;
+    return (p) => {
+      if (p.phase === 'downloading') {
+        if (!started) {
+          started = true;
+          this.log(
+            `tts-local: first use — downloading ${voice.id} (~${voice.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(`tts-local: downloading ${voice.id} … ${lastPct}%`);
+          }
+        }
+      } else if (p.phase === 'extracting' && !extracting) {
+        extracting = true;
+        this.log(`tts-local: extracting ${voice.id} …`);
+      } else if (p.phase === 'done' && started) {
+        this.log(`tts-local: ${voice.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 TTS could not load the sherpa-onnx binary (${pkg}). Reinstall @moxxy/plugin-tts-local so its platform dependency is fetched.`
+          : `Local TTS has no sherpa-onnx binary for ${process.platform}-${process.arch}.`,
+        hint: 'Use the OpenAI or ElevenLabs read-aloud 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 createLocalPiperSynthesizer(opts: LocalPiperOptions = {}): LocalPiperSynthesizer {
+  return new LocalPiperSynthesizer(opts);
+}

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,106 @@
+/**
+ * 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.
+ */
+
+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 TTS 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 synthesize, 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 === 'synthesize' &&
+    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 OfflineTts is not re-entrant, and processing
+  // one at a time keeps memory bounded under a burst of read-aloud calls.
+  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();
+}

package/src/voices.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_POLISH_VOICE_ID,
+  DEFAULT_VOICE_ID,
+  findVoice,
+  requireVoice,
+  routeVoice,
+  VOICE_CATALOG,
+  voiceIds,
+} from './voices.js';
+
+describe('VOICE_CATALOG', () => {
+  it('pins the three Piper voices with their sherpa checksum.txt sha256s', () => {
+    // These MUST match sherpa-onnx's tts-models/checksum.txt verbatim — the
+    // integrity story depends on them not drifting.
+    const byId = Object.fromEntries(VOICE_CATALOG.map((v) => [v.id, v]));
+    expect(byId['en_US-amy-medium']?.sha256).toBe(
+      '9a5d1fc497f85e8022b785bff5f8105203b1e33099ee6265203efc70b0cb0264',
+    );
+    expect(byId['pl_PL-gosia-medium']?.sha256).toBe(
+      '75bd34dcbdc4dd98d763954756b4b34b4208100497c836381542e4d73dcefa9c',
+    );
+    expect(byId['pl_PL-darkman-medium']?.sha256).toBe(
+      '444727aa46eb6db645a2bc88fe73868e4bd7596b7f56ca39fad5ef53c41210d4',
+    );
+  });
+
+  it('derives archive/model paths and language consistently', () => {
+    for (const v of VOICE_CATALOG) {
+      expect(v.archiveRootDir).toBe(`vits-piper-${v.id}`);
+      expect(v.modelFile).toBe(`${v.id}.onnx`);
+      expect(v.url).toBe(
+        `https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-${v.id}.tar.bz2`,
+      );
+      expect(/^[0-9a-f]{64}$/.test(v.sha256)).toBe(true);
+    }
+    expect(VOICE_CATALOG.filter((v) => v.language === 'pl').map((v) => v.id)).toEqual([
+      'pl_PL-gosia-medium',
+      'pl_PL-darkman-medium',
+    ]);
+  });
+
+  it('exposes the default voice ids from the catalog', () => {
+    expect(findVoice(DEFAULT_VOICE_ID)?.language).toBe('en');
+    expect(findVoice(DEFAULT_POLISH_VOICE_ID)?.language).toBe('pl');
+    expect(voiceIds()).toContain('en_US-amy-medium');
+  });
+});
+
+describe('routeVoice', () => {
+  const cfg = { defaultVoice: DEFAULT_VOICE_ID, polishVoice: DEFAULT_POLISH_VOICE_ID };
+
+  it('uses the default voice with no hints', () => {
+    expect(routeVoice({ ...cfg }).id).toBe('en_US-amy-medium');
+  });
+
+  it('routes pl* language hints to the Polish voice', () => {
+    expect(routeVoice({ ...cfg, language: 'pl' }).id).toBe('pl_PL-gosia-medium');
+    expect(routeVoice({ ...cfg, language: 'pl-PL' }).id).toBe('pl_PL-gosia-medium');
+    expect(routeVoice({ ...cfg, language: 'PL_pl' }).id).toBe('pl_PL-gosia-medium');
+  });
+
+  it('routes a non-pl language to the default voice', () => {
+    expect(routeVoice({ ...cfg, language: 'en-US' }).id).toBe('en_US-amy-medium');
+    expect(routeVoice({ ...cfg, language: 'de' }).id).toBe('en_US-amy-medium');
+  });
+
+  it('lets an explicit requestedVoice override everything', () => {
+    expect(routeVoice({ ...cfg, requestedVoice: 'pl_PL-darkman-medium', language: 'en' }).id).toBe(
+      'pl_PL-darkman-medium',
+    );
+    expect(routeVoice({ ...cfg, requestedVoice: 'en_US-amy-medium', language: 'pl' }).id).toBe(
+      'en_US-amy-medium',
+    );
+  });
+
+  it('honors a configured Polish voice override', () => {
+    expect(routeVoice({ defaultVoice: DEFAULT_VOICE_ID, polishVoice: 'pl_PL-darkman-medium', language: 'pl' }).id).toBe(
+      'pl_PL-darkman-medium',
+    );
+  });
+
+  it('throws a clear CONFIG_INVALID for an unknown requested voice, listing valid ids', () => {
+    try {
+      routeVoice({ ...cfg, requestedVoice: 'xx_ZZ-nobody' });
+      throw new Error('expected a throw');
+    } catch (err) {
+      expect((err as { code?: string }).code).toBe('CONFIG_INVALID');
+      expect((err as Error).message).toContain('xx_ZZ-nobody');
+      expect((err as { hint?: string }).hint).toContain('en_US-amy-medium');
+    }
+  });
+
+  it('throws when a configured polishVoice id is unknown', () => {
+    expect(() => routeVoice({ defaultVoice: DEFAULT_VOICE_ID, polishVoice: 'bogus', language: 'pl' })).toThrow();
+  });
+});
+
+describe('requireVoice', () => {
+  it('returns the entry for a valid id', () => {
+    expect(requireVoice('en_US-amy-medium', 'voice').id).toBe('en_US-amy-medium');
+  });
+  it('throws CONFIG_INVALID naming the field for an unknown id', () => {
+    expect(() => requireVoice('nope', 'polishVoice')).toThrow(/Unknown local voice/);
+  });
+});