feat(voice): match local and macOS voices to the language of the text

Text-to-speech picked one voice regardless of what language a reply was in. A dependency-free language detector (script, marker letters, function words) now decides the language of the whole message once; with the new "Match the voice to the language of the text" setting the local provider switches to a catalog model for that language (Kokoro zh/en and Piper models for 12 languages, downloaded on first use like the existing model) and macOS say switches to an installed voice whose locale matches. The local voice picker lists voices of every installed model, and the settings show which language models are on disk. The Ukrainian Piper medium build is a character-level model that sherpa-onnx turns into noise, so the espeak-based Lada build is used instead. Claude-Session: https://claude.ai/code/session_017TK5JAYDfT3Fotc23UEg98
2026-08-30 02:24:22 +03:00
parent 49f0a9e62f
commit 391f938334
29 changed files with 949 additions and 115 deletions
@@ -68,9 +68,19 @@ export const LOCAL_STT_MODEL_CATALOG = {
 * Local text-to-speech models (sherpa-onnx OfflineTts). Downloaded and
 * managed through the same pipeline as the STT models.
 */
+/**
+ * Local text-to-speech models (sherpa-onnx OfflineTts). Downloaded and
+ * managed through the same pipeline as the STT models.
+ *
+ * `languages` lists the languages a model speaks well; the speech service
+ * uses it to pick a model for the language a text is written in. Kokoro
+ * models carry speaker ids (`voices`); a Piper model is one voice for one
+ * language. `lexicon` entries are joined with commas for sherpa-onnx.
+ */
 export const LOCAL_TTS_MODEL_CATALOG = {
  'kokoro-en-v0_19': {
    type: 'kokoro',
+    languages: ['en'],
    archiveUrl:
      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/kokoro-en-v0_19.tar.bz2',
    extractedDir: 'kokoro-en-v0_19',
@@ -82,6 +92,188 @@ export const LOCAL_TTS_MODEL_CATALOG = {
    },
    description: 'Kokoro TTS (English, natural voices)',
  },
+  'kokoro-multi-lang-v1_1': {
+    type: 'kokoro',
+    languages: ['zh', 'en'],
+    // sherpa-onnx wires this Kokoro build for Chinese and English only;
+    // speakers 0-2 are English, 3-102 Chinese.
+    defaultSpeakerByLanguage: { en: 0, zh: 3 },
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/kokoro-multi-lang-v1_1.tar.bz2',
+    extractedDir: 'kokoro-multi-lang-v1_1',
+    files: {
+      model: 'model.onnx',
+      voices: 'voices.bin',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+      lexiconEnglish: 'lexicon-us-en.txt',
+      lexiconChinese: 'lexicon-zh.txt',
+    },
+    lexicon: ['lexiconEnglish', 'lexiconChinese'],
+    description: 'Kokoro TTS (Chinese and English, 103 voices)',
+  },
+  // The larger `ukrainian_tts-medium` build is a character-level model
+  // (`phoneme_type: text`); sherpa-onnx phonemizes every Piper model through
+  // espeak-ng, which turns that one into noise. `vits-coqui-uk-mai` sounds
+  // better but reads Cyrillic only and drops every Latin word (file names,
+  // product names), which is unusable in a coding chat. Lada is an espeak
+  // model: small, but it reads mixed text.
+  'piper-uk_UA-lada-x_low': {
+    type: 'vits',
+    languages: ['uk'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-uk_UA-lada-x_low.tar.bz2',
+    extractedDir: 'vits-piper-uk_UA-lada-x_low',
+    files: {
+      model: 'uk_UA-lada-x_low.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Ukrainian)',
+  },
+  'piper-de_DE-thorsten-medium': {
+    type: 'vits',
+    languages: ['de'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-de_DE-thorsten-medium.tar.bz2',
+    extractedDir: 'vits-piper-de_DE-thorsten-medium',
+    files: {
+      model: 'de_DE-thorsten-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (German)',
+  },
+  'piper-fr_FR-siwis-medium': {
+    type: 'vits',
+    languages: ['fr'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-fr_FR-siwis-medium.tar.bz2',
+    extractedDir: 'vits-piper-fr_FR-siwis-medium',
+    files: {
+      model: 'fr_FR-siwis-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (French)',
+  },
+  'piper-es_ES-davefx-medium': {
+    type: 'vits',
+    languages: ['es'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-es_ES-davefx-medium.tar.bz2',
+    extractedDir: 'vits-piper-es_ES-davefx-medium',
+    files: {
+      model: 'es_ES-davefx-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Spanish)',
+  },
+  'piper-it_IT-paola-medium': {
+    type: 'vits',
+    languages: ['it'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-it_IT-paola-medium.tar.bz2',
+    extractedDir: 'vits-piper-it_IT-paola-medium',
+    files: {
+      model: 'it_IT-paola-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Italian)',
+  },
+  'piper-pt_BR-faber-medium': {
+    type: 'vits',
+    languages: ['pt'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-pt_BR-faber-medium.tar.bz2',
+    extractedDir: 'vits-piper-pt_BR-faber-medium',
+    files: {
+      model: 'pt_BR-faber-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Portuguese (Brazil))',
+  },
+  'piper-pl_PL-gosia-medium': {
+    type: 'vits',
+    languages: ['pl'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-pl_PL-gosia-medium.tar.bz2',
+    extractedDir: 'vits-piper-pl_PL-gosia-medium',
+    files: {
+      model: 'pl_PL-gosia-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Polish)',
+  },
+  'piper-ru_RU-irina-medium': {
+    type: 'vits',
+    languages: ['ru'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-ru_RU-irina-medium.tar.bz2',
+    extractedDir: 'vits-piper-ru_RU-irina-medium',
+    files: {
+      model: 'ru_RU-irina-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Russian)',
+  },
+  'piper-nl_NL-pim-medium': {
+    type: 'vits',
+    languages: ['nl'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-nl_NL-pim-medium.tar.bz2',
+    extractedDir: 'vits-piper-nl_NL-pim-medium',
+    files: {
+      model: 'nl_NL-pim-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Dutch)',
+  },
+  'piper-cs_CZ-jirka-medium': {
+    type: 'vits',
+    languages: ['cs'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-cs_CZ-jirka-medium.tar.bz2',
+    extractedDir: 'vits-piper-cs_CZ-jirka-medium',
+    files: {
+      model: 'cs_CZ-jirka-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Czech)',
+  },
+  'piper-tr_TR-dfki-medium': {
+    type: 'vits',
+    languages: ['tr'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-tr_TR-dfki-medium.tar.bz2',
+    extractedDir: 'vits-piper-tr_TR-dfki-medium',
+    files: {
+      model: 'tr_TR-dfki-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Turkish)',
+  },
+  'piper-sv_SE-nst-medium': {
+    type: 'vits',
+    languages: ['sv'],
+    archiveUrl:
+      'https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-sv_SE-nst-medium.tar.bz2',
+    extractedDir: 'vits-piper-sv_SE-nst-medium',
+    files: {
+      model: 'sv_SE-nst-medium.onnx',
+      tokens: 'tokens.txt',
+      espeakData: 'espeak-ng-data',
+    },
+    description: 'Piper TTS (Swedish)',
+  },
 };

 export const DEFAULT_LOCAL_STT_MODEL = 'parakeet-tdt-0.6b-v2-int8';
@@ -131,6 +323,34 @@ export function getLocalSttModelSpec(modelId) {
  };
 }

+/**
+ * The local TTS model to use for a language, preferring the model the user
+ * selected when it speaks that language. Returns null when no catalog model
+ * covers the language, in which case callers keep the selected model.
+ * @param {string} language BCP-47 primary subtag (`uk`, `zh`...)
+ * @param {string} [preferredModelId]
+ * @returns {string | null}
+ */
+export function resolveLocalTtsModelForLanguage(language, preferredModelId) {
+  const speaks = (modelId) => LOCAL_TTS_MODEL_CATALOG[modelId]?.languages?.includes(language) === true;
+  if (preferredModelId && speaks(preferredModelId)) return preferredModelId;
+  const candidate = LOCAL_TTS_MODEL_IDS.find(speaks);
+  return candidate ?? null;
+}
+
+/**
+ * The speaker id a model should use for a language when the caller's
+ * speaker was chosen for another language. `undefined` keeps the caller's
+ * speaker.
+ * @param {string} modelId
+ * @param {string} language
+ * @returns {number | undefined}
+ */
+export function getLocalTtsDefaultSpeaker(modelId, language) {
+  const speaker = LOCAL_TTS_MODEL_CATALOG[modelId]?.defaultSpeakerByLanguage?.[language];
+  return Number.isInteger(speaker) ? speaker : undefined;
+}
+
 /**
 * @param {string} modelsDir
 * @param {string} modelId
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_LOCAL_TTS_MODEL,
+  LOCAL_TTS_MODEL_CATALOG,
+  getLocalSttModelSpec,
+  getLocalTtsDefaultSpeaker,
+  resolveLocalTtsModelForLanguage,
+} from './model-catalog.js';
+
+describe('local TTS catalog', () => {
+  it('keeps the selected model when it speaks the language', () => {
+    expect(resolveLocalTtsModelForLanguage('en', DEFAULT_LOCAL_TTS_MODEL)).toBe(DEFAULT_LOCAL_TTS_MODEL);
+    expect(resolveLocalTtsModelForLanguage('zh', 'kokoro-multi-lang-v1_1')).toBe('kokoro-multi-lang-v1_1');
+  });
+
+  it('picks a catalog model for a language the selected model lacks', () => {
+    expect(resolveLocalTtsModelForLanguage('uk', DEFAULT_LOCAL_TTS_MODEL)).toBe('piper-uk_UA-lada-x_low');
+    expect(resolveLocalTtsModelForLanguage('zh', DEFAULT_LOCAL_TTS_MODEL)).toBe('kokoro-multi-lang-v1_1');
+  });
+
+  it('returns null for a language no model covers', () => {
+    expect(resolveLocalTtsModelForLanguage('xx', DEFAULT_LOCAL_TTS_MODEL)).toBeNull();
+  });
+
+  it('gives Chinese a Chinese speaker on the multi-language Kokoro', () => {
+    expect(getLocalTtsDefaultSpeaker('kokoro-multi-lang-v1_1', 'zh')).toBe(3);
+    expect(getLocalTtsDefaultSpeaker('kokoro-multi-lang-v1_1', 'en')).toBe(0);
+    expect(getLocalTtsDefaultSpeaker('piper-uk_UA-lada-x_low', 'uk')).toBeUndefined();
+  });
+
+  it('every TTS entry declares its languages and installable files', () => {
+    for (const [id, spec] of Object.entries(LOCAL_TTS_MODEL_CATALOG)) {
+      expect(spec.languages.length, id).toBeGreaterThan(0);
+      expect(spec.archiveUrl, id).toMatch(/^https:\/\/github\.com\/k2-fsa\/sherpa-onnx\/releases\/download\/tts-models\//);
+      const resolved = getLocalSttModelSpec(id);
+      expect(resolved.requiredFiles, id).toContain(spec.files.model);
+      for (const key of spec.lexicon ?? []) {
+        expect(spec.files[key], `${id} lexicon ${key}`).toBeTruthy();
+      }
+    }
+  });
+});
@@ -1,5 +1,5 @@
 /**
- * Sherpa-onnx offline TTS (Kokoro). Runs inside the dictation worker process
+ * Sherpa-onnx offline TTS (Kokoro and Piper/VITS). Runs inside the dictation worker process
 * only — never load the native addon in the main server process.
 */

@@ -23,20 +23,49 @@ function float32ToPcm16le(samples) {
  return Buffer.from(out.buffer, out.byteOffset, out.byteLength);
 }

+/**
+ * sherpa-onnx model config for one catalog entry. Kokoro carries a voices
+ * bank (speaker ids) and optional lexicons; a Piper/VITS model is a single
+ * voice with espeak-ng phonemization.
+ * @param {{ modelDir: string, type?: string, files: Record<string, string>, lexicon?: string[] }} config
+ */
+function buildModelConfig(config) {
+  const file = (key, label) => {
+    const filePath = path.join(config.modelDir, config.files[key]);
+    assertFileExists(filePath, label);
+    return filePath;
+  };
+  const modelPath = file('model', 'TTS model');
+  const tokensPath = file('tokens', 'TTS tokens');
+
+  if (config.type === 'vits') {
+    // Piper models phonemize through espeak-ng (`espeakData`); character
+    // models (Coqui) read the text directly and carry no espeak data.
+    const dataDir = config.files.espeakData ? file('espeakData', 'TTS espeak-ng dataDir') : '';
+    return { vits: { model: modelPath, tokens: tokensPath, ...(dataDir ? { dataDir } : {}), lengthScale: 1.0 } };
+  }
+
+  const dataDir = file('espeakData', 'TTS espeak-ng dataDir');
+  const voicesPath = file('voices', 'TTS voices');
+  const lexicon = (config.lexicon ?? []).map((key) => file(key, 'TTS lexicon')).join(',');
+  return {
+    kokoro: {
+      model: modelPath,
+      voices: voicesPath,
+      tokens: tokensPath,
+      dataDir,
+      lengthScale: 1.0,
+      ...(lexicon ? { lexicon } : {}),
+    },
+  };
+}
+
 export class SherpaTtsEngine {
  /**
-   * @param {{ modelDir: string, files: { model: string, voices: string, tokens: string, espeakData: string }, numThreads?: number }} config
+   * @param {{ modelDir: string, type?: string, files: Record<string, string>, lexicon?: string[], numThreads?: number }} config
   */
  constructor(config) {
-    const modelPath = path.join(config.modelDir, config.files.model);
-    const voicesPath = path.join(config.modelDir, config.files.voices);
-    const tokensPath = path.join(config.modelDir, config.files.tokens);
-    const dataDir = path.join(config.modelDir, config.files.espeakData);
-
-    assertFileExists(modelPath, 'TTS model');
-    assertFileExists(voicesPath, 'TTS voices');
-    assertFileExists(tokensPath, 'TTS tokens');
-    assertFileExists(dataDir, 'TTS espeak-ng dataDir');
+    const model = buildModelConfig(config);

    const sherpa = loadSherpaOnnxNode();
    if (typeof sherpa.OfflineTts !== 'function') {
@@ -44,15 +73,7 @@ export class SherpaTtsEngine {
    }

    this.tts = new sherpa.OfflineTts({
-      model: {
-        kokoro: {
-          model: modelPath,
-          voices: voicesPath,
-          tokens: tokensPath,
-          dataDir,
-          lengthScale: 1.0,
-        },
-      },
+      model,
      numThreads: config.numThreads ?? 2,
      provider: 'cpu',
      maxNumSentences: 1,
@@ -102,7 +102,9 @@ function getTtsEngine(modelsDir, modelId) {
  const spec = getLocalSttModelSpec(modelId);
  const created = new SherpaTtsEngine({
    modelDir: getLocalSttModelDir(modelsDir, modelId),
+    type: spec.type,
    files: spec.files,
+    lexicon: spec.lexicon,
    numThreads: 2,
  });
  ttsEngines.set(key, created);