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
@@ -11,12 +11,25 @@ live transcript costs O(n^2) work for a result the final decode replaces. The
 composer shows no text while recording and inserts the full transcript on
 stop.

-Local TTS (Kokoro via sherpa-onnx OfflineTts) runs in the same worker process
-and is exposed as `POST /api/dictation/tts/speak` (JSON `{text, speakerId?,
-speed?, model?}` → WAV bytes; 503 with `reasonCode` while the model is
-downloading). TTS models live in the same catalog/downloader as STT models
-(`local/model-catalog.js` `LOCAL_TTS_MODEL_CATALOG`) and are managed by the
-same status/download/delete routes.
+Local TTS (Kokoro and Piper/VITS via sherpa-onnx OfflineTts) runs in the same
+worker process and is exposed as `POST /api/dictation/tts/speak` (JSON
+`{text, speakerId?, speed?, model?, language?, languageSample?}` → WAV bytes; 503 with
+`reasonCode` while the model is downloading). TTS models live in the same
+catalog/downloader as STT models (`local/model-catalog.js`
+`LOCAL_TTS_MODEL_CATALOG`) and are managed by the same status/download/delete
+routes.
+
+Each TTS catalog entry declares the `languages` it speaks. With
+`language: 'auto'` the service detects the language of `languageSample` — the
+whole message the chunk belongs to, sent by the client with every chunk — or
+of `text` when no sample is given
+(`../tts/language-detect.js`, script plus function-word scoring, no
+dependencies) and keeps the caller's model when it speaks that language;
+otherwise it switches to the catalog model for the language, downloading it on
+first use like any other model, and starts from that model's default speaker
+(`defaultSpeakerByLanguage`) instead of the caller's speaker id. A language no
+catalog model covers keeps the caller's model, so text is always spoken. The
+response carries `X-Speech-Model` and `X-Speech-Language`.

 ## Ownership

@@ -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);
@@ -63,6 +63,8 @@ export function createDictationRuntime({
        model: typeof req.body?.model === 'string' ? req.body.model : undefined,
        speakerId: Number.isInteger(req.body?.speakerId) ? req.body.speakerId : undefined,
        speed: typeof req.body?.speed === 'number' ? req.body.speed : undefined,
+        language: req.body?.language === 'auto' ? 'auto' : undefined,
+        languageSample: typeof req.body?.languageSample === 'string' ? req.body.languageSample.slice(0, 4000) : undefined,
      });
      if (result.error) {
        res.status(503).json({
@@ -73,6 +75,8 @@ export function createDictationRuntime({
        return;
      }
      res.setHeader('Content-Type', result.format || 'audio/wav');
+      res.setHeader('X-Speech-Model', result.modelId);
+      if (result.language) res.setHeader('X-Speech-Language', result.language);
      res.send(result.audio);
    } catch (error) {
      res.status(500).json({ error: error?.message || 'Failed to synthesize speech' });
@@ -1,3 +1,4 @@
+import { detectTextLanguage } from '../tts/language-detect.js';
 /**
 * Dictation service: resolves STT providers, tracks local model download
 * state, and exposes a readiness snapshot for the status route.
@@ -16,6 +17,8 @@ import { OpenAICompatibleTranscriptionSession } from './openai-compatible-sessio
 import {
  DEFAULT_LOCAL_STT_MODEL,
  DEFAULT_LOCAL_TTS_MODEL,
+  getLocalTtsDefaultSpeaker,
+  resolveLocalTtsModelForLanguage,
  LOCAL_STT_MODEL_CATALOG,
  LOCAL_STT_MODEL_IDS,
  LOCAL_TTS_MODEL_CATALOG,
@@ -220,10 +223,30 @@ export function createDictationService({ modelsDir }) {
  /**
   * Synthesize speech with the local TTS model. Returns WAV bytes, or a
   * readiness error while the model is missing/downloading.
-   * @param {{ text: string, model?: string, speakerId?: number, speed?: number }} options
+   *
+   * With `language: 'auto'` the text's language decides the model: the
+   * caller's model when it speaks that language, otherwise the catalog
+   * model for it (downloaded on first use, reported as in-progress until it
+   * lands). The caller's speaker id is kept only on the caller's model; a
+   * substitute model starts from its own default speaker for the language.
+   * A language no catalog model covers keeps the caller's model, so text is
+   * never silently dropped.
+   * `languageSample` is the whole message the chunk belongs to (or a prefix
+   * of it): the language is judged on that, never on a short chunk alone.
+   * @param {{ text: string, model?: string, speakerId?: number, speed?: number, language?: string, languageSample?: string }} options
   */
-  const synthesizeSpeech = async ({ text, model, speakerId, speed }) => {
-    const modelId = isLocalTtsModelId(model) ? model : DEFAULT_LOCAL_TTS_MODEL;
+  const synthesizeSpeech = async ({ text, model, speakerId, speed, language, languageSample }) => {
+    const requestedModelId = isLocalTtsModelId(model) ? model : DEFAULT_LOCAL_TTS_MODEL;
+    let modelId = requestedModelId;
+    let resolvedLanguage = null;
+    if (language === 'auto') {
+      resolvedLanguage = detectTextLanguage(languageSample || text).language;
+      const forLanguage = resolveLocalTtsModelForLanguage(resolvedLanguage, requestedModelId);
+      if (forLanguage && forLanguage !== requestedModelId) {
+        modelId = forLanguage;
+        speakerId = getLocalTtsDefaultSpeaker(modelId, resolvedLanguage);
+      }
+    }
    const installed = await isLocalSttModelInstalled(modelsDir, modelId);
    if (!installed) {
      const state = downloadStates.get(modelId);
@@ -251,7 +274,7 @@ export function createDictationService({ modelsDir }) {
      speakerId,
      speed,
    });
-    return { audio: result.audio, format: result.format };
+    return { audio: result.audio, format: result.format, modelId, language: resolvedLanguage };
  };

  /**