@moxxy/plugin-tts-local 0.28.0

package/dist/local-tts.js

@@ -0,0 +1,204 @@
+/**
+ * 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 } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import { ensureModel, } from '@moxxy/model-fetch';
+import { HostClient } from './host-client.js';
+import { resolveSherpaLibDir, sherpaEnv, sherpaPlatformPackage } from './platform.js';
+import { DEFAULT_POLISH_VOICE_ID, DEFAULT_VOICE_ID, requireVoice, routeVoice, } 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) {
+    if (rate === undefined || !Number.isFinite(rate))
+        return 1.0;
+    return Math.min(MAX_SPEED, Math.max(MIN_SPEED, rate));
+}
+/** Process-wide set of live synthesizers so the plugin's `onShutdown` hook can
+ *  kill every sidecar it spawned. */
+const ACTIVE_SYNTHS = new Set();
+/** Shut down every live local synthesizer (kills their sidecars). */
+export function shutdownLocalTts() {
+    for (const s of ACTIVE_SYNTHS)
+        s.shutdown();
+    ACTIVE_SYNTHS.clear();
+}
+export class LocalPiperSynthesizer {
+    name = LOCAL_PIPER_SYNTHESIZER_NAME;
+    mimeType = 'audio/wav';
+    voiceId;
+    polishVoiceId;
+    numThreads;
+    modelsDir;
+    provider;
+    sidecarPath;
+    ensureModelImpl;
+    fetchImpl;
+    hostFactory;
+    log;
+    host = null;
+    /** In-flight per-voice download promises — de-dupes concurrent first-use. */
+    ensuring = new Map();
+    constructor(opts = {}) {
+        // 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, opts = {}) {
+        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() {
+        this.host?.shutdown();
+        this.host = null;
+        ACTIVE_SYNTHS.delete(this);
+    }
+    getHost() {
+        this.host ??= this.hostFactory();
+        return this.host;
+    }
+    /** Resolve on-disk paths for `voice`, downloading + extracting it once. */
+    async ensureVoice(voice, signal) {
+        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);
+    }
+    voicePaths(voice, dir) {
+        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`). */
+    makeProgressLogger(voice) {
+        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. */
+    defaultHost() {
+        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 = {}) {
+    return new LocalPiperSynthesizer(opts);
+}
+//# sourceMappingURL=local-tts.js.map

package/dist/local-tts.js.map

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

package/dist/platform.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+/** 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;;;;;;;;;;;;;GAaG;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,93 @@
+/**
+ * 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 = {
+    '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;;;;;;;;;;;;;GAaG;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 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.
+ */
+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 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, } 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() {
+    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 === 'synthesize' &&
+        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 OfflineTts is not re-entrant, and processing
+    // one at a time keeps memory bounded under a burst of read-aloud calls.
+    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,4EAA4E;IAC5E,wEAAwE;IACxE,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"}

package/dist/voices.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The pinned local voice catalog.
+ *
+ * Every voice is a Piper VITS model published by the sherpa-onnx project as a
+ * `.tar.bz2` under its `tts-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>.onnx`, `tokens.txt`, and `espeak-ng-data/`.
+ */
+export type VoiceLanguage = 'en' | 'pl';
+export interface VoiceEntry {
+    /** Stable voice id, e.g. `en_US-amy-medium` (also the `set_voice` name). */
+    readonly id: string;
+    /** BCP-47 primary language subtag used for language routing. */
+    readonly language: VoiceLanguage;
+    /** Human label for UI surfaces. */
+    readonly label: string;
+    /** Pinned archive URL (sherpa-onnx GitHub release). */
+    readonly url: string;
+    /** Pinned hex sha256 of the archive (from the release checksum.txt). */
+    readonly sha256: string;
+    /** Top directory the archive extracts to (`vits-piper-<id>`). */
+    readonly archiveRootDir: string;
+    /** The ONNX model filename inside `archiveRootDir` (`<id>.onnx`). */
+    readonly modelFile: string;
+    /** Approximate download size in MB (for the one-time first-use notice). */
+    readonly approxMb: number;
+}
+export declare const VOICE_CATALOG: readonly VoiceEntry[];
+export declare const DEFAULT_VOICE_ID = "en_US-amy-medium";
+export declare const DEFAULT_POLISH_VOICE_ID = "pl_PL-gosia-medium";
+/** All valid voice ids, for error messages and validation. */
+export declare function voiceIds(): string[];
+export declare function findVoice(id: string): VoiceEntry | undefined;
+/** Resolve a voice 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 requireVoice(id: string, field: string): VoiceEntry;
+export interface RouteVoiceInput {
+    /** Explicit per-call voice id (`SynthesizeOptions.voice`) — overrides all. */
+    readonly requestedVoice?: string;
+    /** Per-call BCP-47 language hint (`SynthesizeOptions.language`). */
+    readonly language?: string;
+    /** Configured default (non-Polish) voice id. */
+    readonly defaultVoice: string;
+    /** Configured Polish voice id. */
+    readonly polishVoice: string;
+}
+/**
+ * Pick the voice for a synthesis call:
+ *   1. an explicit `requestedVoice` (a catalog id) wins outright;
+ *   2. else a `language` starting with `pl` routes to the Polish voice;
+ *   3. else the configured default voice.
+ * An unknown id (in any of the three) throws a clear `CONFIG_INVALID` error.
+ */
+export declare function routeVoice(input: RouteVoiceInput): VoiceEntry;
+//# sourceMappingURL=voices.d.ts.map

package/dist/voices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voices.d.ts","sourceRoot":"","sources":["../src/voices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,IAAI,CAAC;AAExC,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAwBD,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,EAsB9C,CAAC;AAEF,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D,8DAA8D;AAC9D,wBAAgB,QAAQ,IAAI,MAAM,EAAE,CAEnC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE5D;AAED;uEACuE;AACvE,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAWlE;AAED,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU,CAS7D"}

package/dist/voices.js

@@ -0,0 +1,71 @@
+/**
+ * The pinned local voice catalog.
+ *
+ * Every voice is a Piper VITS model published by the sherpa-onnx project as a
+ * `.tar.bz2` under its `tts-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>.onnx`, `tokens.txt`, and `espeak-ng-data/`.
+ */
+import { MoxxyError } from '@moxxy/sdk';
+const RELEASE_BASE = 'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models';
+function piperVoice(id, language, label, sha256, approxMb) {
+    const archiveRootDir = `vits-piper-${id}`;
+    return {
+        id,
+        language,
+        label,
+        url: `${RELEASE_BASE}/${archiveRootDir}.tar.bz2`,
+        sha256,
+        archiveRootDir,
+        modelFile: `${id}.onnx`,
+        approxMb,
+    };
+}
+export const VOICE_CATALOG = [
+    piperVoice('en_US-amy-medium', 'en', 'Amy (English, US)', '9a5d1fc497f85e8022b785bff5f8105203b1e33099ee6265203efc70b0cb0264', 63),
+    piperVoice('pl_PL-gosia-medium', 'pl', 'Gosia (Polish)', '75bd34dcbdc4dd98d763954756b4b34b4208100497c836381542e4d73dcefa9c', 63),
+    piperVoice('pl_PL-darkman-medium', 'pl', 'Darkman (Polish)', '444727aa46eb6db645a2bc88fe73868e4bd7596b7f56ca39fad5ef53c41210d4', 63),
+];
+export const DEFAULT_VOICE_ID = 'en_US-amy-medium';
+export const DEFAULT_POLISH_VOICE_ID = 'pl_PL-gosia-medium';
+/** All valid voice ids, for error messages and validation. */
+export function voiceIds() {
+    return VOICE_CATALOG.map((v) => v.id);
+}
+export function findVoice(id) {
+    return VOICE_CATALOG.find((v) => v.id === id);
+}
+/** Resolve a voice 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 requireVoice(id, field) {
+    const entry = findVoice(id);
+    if (!entry) {
+        throw new MoxxyError({
+            code: 'CONFIG_INVALID',
+            message: `Unknown local voice ${JSON.stringify(id)} (${field}).`,
+            hint: `Valid voices: ${voiceIds().join(', ')}.`,
+            context: { field, voice: id },
+        });
+    }
+    return entry;
+}
+/**
+ * Pick the voice for a synthesis call:
+ *   1. an explicit `requestedVoice` (a catalog id) wins outright;
+ *   2. else a `language` starting with `pl` routes to the Polish voice;
+ *   3. else the configured default voice.
+ * An unknown id (in any of the three) throws a clear `CONFIG_INVALID` error.
+ */
+export function routeVoice(input) {
+    if (input.requestedVoice) {
+        return requireVoice(input.requestedVoice, 'voice');
+    }
+    const lang = (input.language ?? '').trim().toLowerCase();
+    if (lang.startsWith('pl')) {
+        return requireVoice(input.polishVoice, 'polishVoice');
+    }
+    return requireVoice(input.defaultVoice, 'voice');
+}
+//# sourceMappingURL=voices.js.map

package/dist/voices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voices.js","sourceRoot":"","sources":["../src/voices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAuBxC,MAAM,YAAY,GAAG,oEAAoE,CAAC;AAE1F,SAAS,UAAU,CACjB,EAAU,EACV,QAAuB,EACvB,KAAa,EACb,MAAc,EACd,QAAgB;IAEhB,MAAM,cAAc,GAAG,cAAc,EAAE,EAAE,CAAC;IAC1C,OAAO;QACL,EAAE;QACF,QAAQ;QACR,KAAK;QACL,GAAG,EAAE,GAAG,YAAY,IAAI,cAAc,UAAU;QAChD,MAAM;QACN,cAAc;QACd,SAAS,EAAE,GAAG,EAAE,OAAO;QACvB,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAA0B;IAClD,UAAU,CACR,kBAAkB,EAClB,IAAI,EACJ,mBAAmB,EACnB,kEAAkE,EAClE,EAAE,CACH;IACD,UAAU,CACR,oBAAoB,EACpB,IAAI,EACJ,gBAAgB,EAChB,kEAAkE,EAClE,EAAE,CACH;IACD,UAAU,CACR,sBAAsB,EACtB,IAAI,EACJ,kBAAkB,EAClB,kEAAkE,EAClE,EAAE,CACH;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AACnD,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAE5D,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,uBAAuB,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,KAAK,IAAI;YAChE,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;AAaD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QACzB,OAAO,YAAY,CAAC,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACzD,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,OAAO,YAAY,CAAC,KAAK,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC"}

package/dist/wav.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Minimal float32 → PCM16 mono WAV encoder.
+ *
+ * sherpa-onnx hands back `{ samples: Float32Array in [-1, 1], sampleRate }`.
+ * Read-aloud surfaces and channel voice replies want playable container bytes,
+ * so we wrap the samples in a canonical 44-byte RIFF/WAVE header + 16-bit PCM
+ * little-endian data. Kept dependency-free and self-contained (deliberately NOT
+ * imported from plugin-stt-whisper) and covered by golden tests — the header
+ * offsets are load-bearing.
+ */
+/** Bytes in the RIFF/WAVE header preceding the PCM data. */
+export declare const WAV_HEADER_BYTES = 44;
+/**
+ * Encode float samples as a mono 16-bit PCM WAV. `sampleRate` must be a
+ * positive integer (sherpa reports e.g. 22050). Samples are clamped to
+ * [-1, 1]; non-finite samples encode as silence.
+ */
+export declare function encodeWav(samples: Float32Array, sampleRate: number): Uint8Array;
+//# sourceMappingURL=wav.d.ts.map

package/dist/wav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wav.d.ts","sourceRoot":"","sources":["../src/wav.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAMnC;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAyC/E"}