@moxxy/plugin-tts-local 0.28.0

package/src/voices.ts

@@ -0,0 +1,135 @@
+/**
+ * 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';
+
+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;
+}
+
+const RELEASE_BASE = 'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models';
+
+function piperVoice(
+  id: string,
+  language: VoiceLanguage,
+  label: string,
+  sha256: string,
+  approxMb: number,
+): VoiceEntry {
+  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: readonly VoiceEntry[] = [
+  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(): string[] {
+  return VOICE_CATALOG.map((v) => v.id);
+}
+
+export function findVoice(id: string): VoiceEntry | undefined {
+  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: string, field: string): VoiceEntry {
+  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;
+}
+
+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 function routeVoice(input: RouteVoiceInput): VoiceEntry {
+  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');
+}

package/src/wav.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { encodeWav, WAV_HEADER_BYTES } from './wav.js';
+
+function ascii(bytes: Uint8Array, start: number, len: number): string {
+  return String.fromCharCode(...bytes.subarray(start, start + len));
+}
+
+describe('encodeWav', () => {
+  it('writes a canonical mono PCM16 header (golden)', () => {
+    const samples = new Float32Array([0, 1, -1, 0.5]);
+    const wav = encodeWav(samples, 8000);
+    const view = new DataView(wav.buffer, wav.byteOffset, wav.byteLength);
+    const dataSize = samples.length * 2;
+
+    expect(wav.byteLength).toBe(WAV_HEADER_BYTES + dataSize);
+    expect(ascii(wav, 0, 4)).toBe('RIFF');
+    expect(view.getUint32(4, true)).toBe(36 + dataSize);
+    expect(ascii(wav, 8, 4)).toBe('WAVE');
+    expect(ascii(wav, 12, 4)).toBe('fmt ');
+    expect(view.getUint32(16, true)).toBe(16); // PCM fmt size
+    expect(view.getUint16(20, true)).toBe(1); // PCM
+    expect(view.getUint16(22, true)).toBe(1); // mono
+    expect(view.getUint32(24, true)).toBe(8000); // sample rate
+    expect(view.getUint32(28, true)).toBe(8000 * 2); // byte rate (mono, 2 bytes)
+    expect(view.getUint16(32, true)).toBe(2); // block align
+    expect(view.getUint16(34, true)).toBe(16); // bits per sample
+    expect(ascii(wav, 36, 4)).toBe('data');
+    expect(view.getUint32(40, true)).toBe(dataSize);
+  });
+
+  it('maps full-scale samples to the int16 range edges', () => {
+    const wav = encodeWav(new Float32Array([0, 1, -1, 0.5]), 8000);
+    const view = new DataView(wav.buffer, wav.byteOffset, wav.byteLength);
+    expect(view.getInt16(WAV_HEADER_BYTES + 0, true)).toBe(0);
+    expect(view.getInt16(WAV_HEADER_BYTES + 2, true)).toBe(32767); // +1.0
+    expect(view.getInt16(WAV_HEADER_BYTES + 4, true)).toBe(-32768); // -1.0
+    expect(view.getInt16(WAV_HEADER_BYTES + 6, true)).toBe(16384); // +0.5
+  });
+
+  it('clamps out-of-range samples and encodes NaN as silence', () => {
+    const wav = encodeWav(new Float32Array([2, -2, Number.NaN]), 16000);
+    const view = new DataView(wav.buffer, wav.byteOffset, wav.byteLength);
+    expect(view.getInt16(WAV_HEADER_BYTES + 0, true)).toBe(32767);
+    expect(view.getInt16(WAV_HEADER_BYTES + 2, true)).toBe(-32768);
+    expect(view.getInt16(WAV_HEADER_BYTES + 4, true)).toBe(0);
+  });
+
+  it('encodes an empty sample array to a bare 44-byte header', () => {
+    const wav = encodeWav(new Float32Array([]), 22050);
+    expect(wav.byteLength).toBe(WAV_HEADER_BYTES);
+  });
+
+  it('rejects an invalid sample rate', () => {
+    expect(() => encodeWav(new Float32Array([0]), 0)).toThrow();
+    expect(() => encodeWav(new Float32Array([0]), Number.NaN)).toThrow();
+  });
+});

package/src/wav.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 const WAV_HEADER_BYTES = 44;
+
+function writeAscii(view: DataView, offset: number, text: string): void {
+  for (let i = 0; i < text.length; i += 1) view.setUint8(offset + i, text.charCodeAt(i));
+}
+
+/**
+ * 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 function encodeWav(samples: Float32Array, sampleRate: number): Uint8Array {
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+    throw new Error(`encodeWav: invalid sampleRate ${sampleRate}`);
+  }
+  const rate = Math.round(sampleRate);
+  const numSamples = samples.length;
+  const bytesPerSample = 2; // PCM16
+  const blockAlign = bytesPerSample; // mono
+  const byteRate = rate * blockAlign;
+  const dataSize = numSamples * bytesPerSample;
+  const buffer = new ArrayBuffer(WAV_HEADER_BYTES + dataSize);
+  const view = new DataView(buffer);
+
+  // RIFF chunk descriptor
+  writeAscii(view, 0, 'RIFF');
+  view.setUint32(4, 36 + dataSize, true); // ChunkSize = 4 + (8 + Subchunk1) + (8 + data)
+  writeAscii(view, 8, 'WAVE');
+  // fmt subchunk
+  writeAscii(view, 12, 'fmt ');
+  view.setUint32(16, 16, true); // Subchunk1Size for PCM
+  view.setUint16(20, 1, true); // AudioFormat = 1 (PCM)
+  view.setUint16(22, 1, true); // NumChannels = 1 (mono)
+  view.setUint32(24, rate, true); // SampleRate
+  view.setUint32(28, byteRate, true); // ByteRate
+  view.setUint16(32, blockAlign, true); // BlockAlign
+  view.setUint16(34, 16, true); // BitsPerSample
+  // data subchunk
+  writeAscii(view, 36, 'data');
+  view.setUint32(40, dataSize, true);
+
+  let offset = WAV_HEADER_BYTES;
+  for (let i = 0; i < numSamples; i += 1) {
+    const raw = samples[i];
+    const s = Number.isFinite(raw as number) ? Math.max(-1, Math.min(1, raw as number)) : 0;
+    // Asymmetric scaling so full-scale positive/negative map to the int16 range
+    // edges without overflow.
+    const int16 = s < 0 ? Math.round(s * 0x8000) : Math.round(s * 0x7fff);
+    view.setInt16(offset, int16, true);
+    offset += 2;
+  }
+  return new Uint8Array(buffer);
+}