@moxxy/plugin-tts-local 0.28.0

package/src/host-protocol.ts

@@ -0,0 +1,127 @@
+/**
+ * The tiny JSON message protocol spoken between the parent (host-client) and
+ * the forked sherpa sidecar, plus the pure per-message handler the sidecar
+ * runs. Kept free of `node:child_process` so BOTH sides can import it (the
+ * parent for the types, the child for the handler) without dragging fork
+ * plumbing into either bundle.
+ *
+ * Wire shape (over the fork IPC channel, `serialization: 'advanced'` so the
+ * Float32Array round-trips intact):
+ *   parent → child:  SynthesizeRequest
+ *   child  → parent: HostReply
+ */
+
+/** One synthesis request. Carries the full model config so the sidecar is
+ *  stateless-per-message except for a model cache keyed by `voiceKey`. */
+export interface SynthesizeRequest {
+  readonly id: number;
+  readonly type: 'synthesize';
+  /** Cache key for the loaded model (the absolute `.onnx` path). */
+  readonly voiceKey: string;
+  /** Absolute path to the VITS `.onnx` model. */
+  readonly model: string;
+  /** Absolute path to `tokens.txt`. */
+  readonly tokens: string;
+  /** Absolute path to the `espeak-ng-data` directory. */
+  readonly dataDir: string;
+  /** Inference thread count. */
+  readonly numThreads: number;
+  /** Compute provider (`cpu`). */
+  readonly provider: string;
+  /** Text to speak. */
+  readonly text: string;
+  /** Speaker id within the model (0 for single-speaker Piper voices). */
+  readonly sid: number;
+  /** Speaking-rate multiplier already clamped by the caller. */
+  readonly speed: number;
+}
+
+export type HostRequest = SynthesizeRequest;
+
+export type HostErrorKind =
+  /** Model failed to load (bad/absent files, unsupported arch, addon dlopen). */
+  | 'init'
+  /** Synthesis itself threw. */
+  | 'runtime';
+
+export type HostReply =
+  | {
+      readonly id: number;
+      readonly ok: true;
+      readonly sampleRate: number;
+      /** Mono PCM in [-1, 1]; structured-cloned intact over advanced IPC. */
+      readonly samples: Float32Array;
+    }
+  | {
+      readonly id: number;
+      readonly ok: false;
+      readonly error: { readonly message: string; readonly kind: HostErrorKind };
+    };
+
+/** The subset of the sherpa-onnx-node surface the sidecar uses. Declared here
+ *  (rather than leaning on the addon's ambient types) so the handler is
+ *  unit-testable with a fake module and typechecks without the native addon. */
+export interface SherpaOfflineTts {
+  generateAsync(args: {
+    text: string;
+    sid: number;
+    speed: number;
+  }): Promise<{ samples: Float32Array; sampleRate: number }>;
+}
+
+export interface SherpaModule {
+  OfflineTts: new (config: unknown) => SherpaOfflineTts;
+}
+
+/** Lazily load the native sherpa module (so a dlopen failure surfaces as a
+ *  classified reply, not a boot crash). */
+export type LoadSherpa = () => SherpaModule;
+
+export type HostMessageHandler = (req: HostRequest) => Promise<HostReply>;
+
+/**
+ * Build the sidecar's message handler. Loads the sherpa module on first use and
+ * caches one `OfflineTts` per `voiceKey` so repeated calls on the same voice
+ * reuse the loaded model. Every failure becomes a typed `ok:false` reply —
+ * nothing throws out of `handle`.
+ */
+export function createMessageHandler(loadSherpa: LoadSherpa): HostMessageHandler {
+  const cache = new Map<string, SherpaOfflineTts>();
+  let mod: SherpaModule | null = null;
+
+  return async function handle(req: HostRequest): Promise<HostReply> {
+    let tts = cache.get(req.voiceKey);
+    if (!tts) {
+      try {
+        mod ??= loadSherpa();
+        tts = new mod.OfflineTts({
+          model: {
+            vits: { model: req.model, tokens: req.tokens, dataDir: req.dataDir },
+            numThreads: req.numThreads,
+            provider: req.provider,
+            debug: false,
+          },
+          maxNumSentences: 1,
+        });
+        cache.set(req.voiceKey, tts);
+      } catch (err) {
+        return { id: req.id, ok: false, error: { message: errMsg(err), kind: 'init' } };
+      }
+    }
+
+    try {
+      const out = await tts.generateAsync({ text: req.text, sid: req.sid, speed: req.speed });
+      const samples =
+        out.samples instanceof Float32Array
+          ? out.samples
+          : Float32Array.from(out.samples as ArrayLike<number>);
+      return { id: req.id, ok: true, sampleRate: out.sampleRate, samples };
+    } catch (err) {
+      return { id: req.id, ok: false, error: { message: errMsg(err), kind: 'runtime' } };
+    }
+  };
+}
+
+function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+import { definePlugin, defineSynthesizer, type Plugin } from '@moxxy/sdk';
+
+import {
+  createLocalPiperSynthesizer,
+  LOCAL_PIPER_SYNTHESIZER_NAME,
+  shutdownLocalTts,
+  type LocalPiperOptions,
+} from './local-tts.js';
+
+export {
+  LocalPiperSynthesizer,
+  createLocalPiperSynthesizer,
+  clampSpeed,
+  shutdownLocalTts,
+  LOCAL_PIPER_SYNTHESIZER_NAME,
+  type LocalPiperOptions,
+  type VoiceModelPaths,
+} from './local-tts.js';
+export { encodeWav, WAV_HEADER_BYTES } from './wav.js';
+export {
+  VOICE_CATALOG,
+  voiceIds,
+  findVoice,
+  routeVoice,
+  requireVoice,
+  DEFAULT_VOICE_ID,
+  DEFAULT_POLISH_VOICE_ID,
+  type VoiceEntry,
+  type VoiceLanguage,
+} from './voices.js';
+export { HostClient, type HostClientLike, type ForkLike, type ChildHandle } from './host-client.js';
+export {
+  sherpaPlatformPackage,
+  resolveSherpaLibDir,
+  sherpaEnv,
+  libraryPathVar,
+} from './platform.js';
+
+export interface BuildLocalTtsPluginOptions {
+  /** Build-time defaults / test seams for the synthesizer (injected
+   *  `ensureModelImpl`, `hostFactory`, `fetchImpl`, `modelsDir`, `log`). */
+  readonly defaults?: LocalPiperOptions;
+}
+
+/**
+ * Build the @moxxy/plugin-tts-local plugin. Registers exactly one synthesizer,
+ * `local-piper`, backed by sherpa-onnx Piper voices running in a forked
+ * sidecar. Side-effect free at load: no model is downloaded and no process is
+ * spawned until the first `synthesize`. Per-activation config
+ * (`session.synthesizers.setActive('local-piper', { voice, polishVoice,
+ * numThreads })`) overrides the build-time defaults.
+ */
+export function buildLocalTtsPlugin(opts: BuildLocalTtsPluginOptions = {}): Plugin {
+  const defaults = opts.defaults ?? {};
+  return definePlugin({
+    name: '@moxxy/plugin-tts-local',
+    version: '0.0.0',
+    synthesizers: [
+      defineSynthesizer({
+        name: LOCAL_PIPER_SYNTHESIZER_NAME,
+        displayName: 'Local (Piper — offline, EN+PL)',
+        // `create` runs lazily and may re-run (buildOnRead) — keep it cheap and
+        // side-effect free; the sidecar + download happen on first synthesize.
+        create: (ctx) =>
+          createLocalPiperSynthesizer({ ...defaults, ...configToOptions(ctx.config) }),
+      }),
+    ],
+    // Kill every spawned sidecar when the session/runner shuts down.
+    hooks: { onShutdown: () => shutdownLocalTts() },
+  });
+}
+
+/** Narrow the untrusted per-activation config into typed options — only the
+ *  known string `voice` / `polishVoice` and a positive-integer `numThreads` are
+ *  honored so a malformed config can't break `create` or route to a bad voice
+ *  (unknown ids are caught by `requireVoice` at construction). */
+function configToOptions(config: Record<string, unknown>): Partial<LocalPiperOptions> {
+  const out: { -readonly [K in keyof LocalPiperOptions]?: LocalPiperOptions[K] } = {};
+  if (typeof config.voice === 'string' && config.voice) out.voice = config.voice;
+  if (typeof config.polishVoice === 'string' && config.polishVoice) {
+    out.polishVoice = config.polishVoice;
+  }
+  if (typeof config.numThreads === 'number' && Number.isInteger(config.numThreads) && config.numThreads > 0) {
+    out.numThreads = config.numThreads;
+  }
+  return out;
+}
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default buildLocalTtsPlugin();

package/src/live.test.ts

@@ -0,0 +1,56 @@
+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 { createLocalPiperSynthesizer } from './local-tts.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-tts-local build`).
+const SIDECAR_PATH = fileURLToPath(new URL('../dist/sidecar.js', import.meta.url));
+
+/**
+ * Opt-in end-to-end test that REALLY downloads a voice and runs the native
+ * sherpa sidecar — off by default (it fetches ~64 MB and needs the platform
+ * binary). Run manually with:
+ *
+ *   MOXXY_TTS_LOCAL_LIVE=1 pnpm -F @moxxy/plugin-tts-local test
+ */
+const LIVE = !!process.env.MOXXY_TTS_LOCAL_LIVE;
+
+let modelsDir: string;
+beforeAll(async () => {
+  if (!LIVE) return;
+  modelsDir = await mkdtemp(path.join(tmpdir(), 'tts-local-live-'));
+});
+afterAll(async () => {
+  if (modelsDir) await rm(modelsDir, { recursive: true, force: true });
+});
+
+describe.skipIf(!LIVE)('local TTS (live, real download + native sidecar)', () => {
+  it('synthesizes English audio', async () => {
+    const synth = createLocalPiperSynthesizer({ modelsDir, sidecarPath: SIDECAR_PATH });
+    try {
+      const out = await synth.synthesize('Hello from a fully local voice.', { language: 'en' });
+      expect(out.mimeType).toBe('audio/wav');
+      expect(String.fromCharCode(...out.audio.subarray(0, 4))).toBe('RIFF');
+      expect(out.audio.byteLength).toBeGreaterThan(44 + 1000);
+    } finally {
+      synth.shutdown();
+    }
+  }, 600_000);
+
+  it('synthesizes Polish audio', async () => {
+    const synth = createLocalPiperSynthesizer({ modelsDir, sidecarPath: SIDECAR_PATH });
+    try {
+      const out = await synth.synthesize('Dzień dobry, mówię po polsku.', { language: 'pl' });
+      expect(out.mimeType).toBe('audio/wav');
+      expect(out.audio.byteLength).toBeGreaterThan(44 + 1000);
+    } finally {
+      synth.shutdown();
+    }
+  }, 600_000);
+});

package/src/local-tts.test.ts

@@ -0,0 +1,195 @@
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import { ensureModel } from '@moxxy/model-fetch';
+
+import {
+  clampSpeed,
+  createLocalPiperSynthesizer,
+  type LocalPiperOptions,
+} from './local-tts.js';
+import { buildLocalTtsPlugin, LOCAL_PIPER_SYNTHESIZER_NAME } from './index.js';
+import type { HostClientLike } from './host-client.js';
+import type { HostRequest } from './host-protocol.js';
+
+/** A fake host recording each synthesize request; returns canned samples. */
+function fakeHost(): { 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 synthesize(req) {
+      state.reqs.push(req);
+      return { samples: new Float32Array([0.1, -0.1, 0.2]), sampleRate: 22050 };
+    },
+    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 makeSynth(over: Partial<LocalPiperOptions> = {}): {
+  synth: ReturnType<typeof createLocalPiperSynthesizer>;
+  host: ReturnType<typeof fakeHost>;
+  ensure: ReturnType<typeof fakeEnsure>;
+} {
+  const host = fakeHost();
+  const ensure = fakeEnsure();
+  const synth = createLocalPiperSynthesizer({
+    modelsDir: '/models/tts',
+    ensureModelImpl: ensure.impl,
+    hostFactory: () => host.host,
+    log: () => {},
+    ...over,
+  });
+  return { synth, host, ensure };
+}
+
+describe('LocalPiperSynthesizer.synthesize', () => {
+  it('defaults to the English voice and returns WAV bytes', async () => {
+    const { synth, host, ensure } = makeSynth();
+    const out = await synth.synthesize('hello world');
+    expect(out.mimeType).toBe('audio/wav');
+    expect(String.fromCharCode(...out.audio.subarray(0, 4))).toBe('RIFF');
+    expect(ensure.urls).toEqual([
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-amy-medium.tar.bz2',
+    ]);
+    // The host got the en model path + default sid/speed.
+    expect(host.reqs[0]!.model).toBe(path.join('/models/tts/en_US-amy-medium/vits-piper-en_US-amy-medium/en_US-amy-medium.onnx'));
+    expect(host.reqs[0]!.dataDir).toContain('espeak-ng-data');
+    expect(host.reqs[0]!.text).toBe('hello world');
+    expect(host.reqs[0]!.speed).toBe(1);
+  });
+
+  it('routes a Polish language hint to the configured Polish voice', async () => {
+    const { synth, host, ensure } = makeSynth();
+    await synth.synthesize('cześć', { language: 'pl-PL' });
+    expect(ensure.urls[0]).toContain('vits-piper-pl_PL-gosia-medium');
+    expect(host.reqs[0]!.model).toContain('pl_PL-gosia-medium');
+  });
+
+  it('lets an explicit voice override language routing', async () => {
+    const { synth, host } = makeSynth();
+    await synth.synthesize('lektor', { language: 'pl', voice: 'pl_PL-darkman-medium' });
+    expect(host.reqs[0]!.model).toContain('pl_PL-darkman-medium');
+  });
+
+  it('honors a configured polishVoice default', async () => {
+    const { synth, host } = makeSynth({ polishVoice: 'pl_PL-darkman-medium' });
+    await synth.synthesize('dzień dobry', { language: 'pl' });
+    expect(host.reqs[0]!.model).toContain('pl_PL-darkman-medium');
+  });
+
+  it('rejects an unknown requested voice with a clear error', async () => {
+    const { synth } = makeSynth();
+    await expect(synth.synthesize('x', { voice: 'no-such-voice' })).rejects.toMatchObject({
+      code: 'CONFIG_INVALID',
+    });
+  });
+
+  it('downloads a given voice only once across calls', async () => {
+    const { synth, ensure } = makeSynth();
+    await synth.synthesize('one');
+    await synth.synthesize('two');
+    await synth.synthesize('three');
+    expect(ensure.urls.length).toBe(1); // en voice ensured once
+  });
+
+  it('maps and clamps rate onto sherpa speed', async () => {
+    const { synth, host } = makeSynth();
+    await synth.synthesize('fast', { rate: 5 });
+    await synth.synthesize('slow', { rate: 0.1 });
+    await synth.synthesize('normal');
+    expect(host.reqs.map((r) => r.speed)).toEqual([2.0, 0.5, 1.0]);
+  });
+
+  it('respects a pre-aborted signal', async () => {
+    const { synth } = makeSynth();
+    const ac = new AbortController();
+    ac.abort(new Error('stop'));
+    await expect(synth.synthesize('x', { signal: ac.signal })).rejects.toThrow(/stop/);
+  });
+
+  it('uses numThreads and provider defaults', async () => {
+    const { synth, host } = makeSynth({ numThreads: 4 });
+    await synth.synthesize('hi');
+    expect(host.reqs[0]!.numThreads).toBe(4);
+    expect(host.reqs[0]!.provider).toBe('cpu');
+    expect(host.reqs[0]!.sid).toBe(0);
+  });
+
+  it('shutdown tears down the host', async () => {
+    const { synth, host } = makeSynth();
+    await synth.synthesize('hi');
+    synth.shutdown();
+    expect(host.shutdowns).toBe(1);
+  });
+});
+
+describe('clampSpeed', () => {
+  it('clamps to 0.5–2.0 and defaults absent/non-finite to 1.0', () => {
+    expect(clampSpeed(undefined)).toBe(1.0);
+    expect(clampSpeed(Number.NaN)).toBe(1.0);
+    expect(clampSpeed(1.3)).toBe(1.3);
+    expect(clampSpeed(9)).toBe(2.0);
+    expect(clampSpeed(0.01)).toBe(0.5);
+  });
+});
+
+describe('constructor validation', () => {
+  it('throws CONFIG_INVALID for an unknown configured voice', () => {
+    expect(() => createLocalPiperSynthesizer({ voice: 'bogus' })).toThrow(/Unknown local voice/);
+  });
+  it('throws CONFIG_INVALID for an unknown configured polishVoice', () => {
+    expect(() => createLocalPiperSynthesizer({ polishVoice: 'nope' })).toThrow(/Unknown local voice/);
+  });
+});
+
+describe('buildLocalTtsPlugin', () => {
+  it('registers exactly one synthesizer named local-piper', () => {
+    const plugin = buildLocalTtsPlugin();
+    expect(plugin.synthesizers).toHaveLength(1);
+    const def = plugin.synthesizers![0]!;
+    expect(def.name).toBe(LOCAL_PIPER_SYNTHESIZER_NAME);
+    expect(def.displayName).toContain('Local');
+  });
+
+  it('create() flows per-activation voice config through to routing', async () => {
+    const host = fakeHost();
+    const ensure = fakeEnsure();
+    const plugin = buildLocalTtsPlugin({
+      defaults: {
+        modelsDir: '/models/tts',
+        ensureModelImpl: ensure.impl,
+        hostFactory: () => host.host,
+        log: () => {},
+      },
+    });
+    const inst = plugin.synthesizers![0]!.create({ config: { voice: 'pl_PL-gosia-medium' } });
+    await inst.synthesize('cześć');
+    expect(host.reqs[0]!.model).toContain('pl_PL-gosia-medium');
+  });
+
+  it('create() rejects an unknown voice in config at construction', () => {
+    const plugin = buildLocalTtsPlugin();
+    expect(() => plugin.synthesizers![0]!.create({ config: { voice: 'bad-id' } })).toThrow();
+  });
+
+  it('exposes an onShutdown hook', () => {
+    const plugin = buildLocalTtsPlugin();
+    expect(typeof plugin.hooks?.onShutdown).toBe('function');
+  });
+});