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

packages/web/server/lib/tts/DOCUMENTATION.md

@@ -11,6 +11,7 @@ This module provides server-side Text-to-Speech services using OpenAI's TTS API.
 - `packages/web/server/lib/text/summarization.js`: Shared text summarization stub and sanitization utilities. It performs no external Zen calls.
 - `packages/web/server/lib/tts/stt.js`: STT proxy for OpenAI-compatible transcription endpoints.
 - `packages/web/server/lib/tts/base-url.js`: shared base URL validation and normalization for custom OpenAI-compatible endpoints.
+- `packages/web/server/lib/tts/language-detect.js`: dependency-free language detection for voice selection (`detectTextLanguage`, `pickVoiceForLanguage`, `languageOfLocale`). Used by the macOS `say` route (`language: 'auto'` switches to an installed voice whose locale matches the text; the response carries `X-Speech-Voice` and `X-Speech-Language`) and by the dictation module's local TTS model choice.
 
 ## Public exports
 

packages/web/server/lib/tts/language-detect.js

@@ -0,0 +1,210 @@
+/**
+ * Language detection for text-to-speech voice selection.
+ *
+ * Picks the language a piece of chat text is written in so a TTS provider
+ * can choose a matching voice or model. Deliberately small and dependency
+ * free: the writing system decides most cases outright, and Latin-script
+ * languages are told apart by function words and characteristic letters.
+ * The answer is a best effort for voice selection, not a linguistic claim —
+ * an unknown language falls back to English rather than failing.
+ */
+
+const SCRIPT_RANGES = [
+  ['hangul', /[가-힯ᄀ-ᇿ㄰-㆏]/g],
+  ['kana', /[぀-ヿ]/g],
+  ['han', /[一-鿿㐀-䶿]/g],
+  ['cyrillic', /[Ѐ-ӿ]/g],
+  ['greek', /[Ͱ-Ͽ]/g],
+  ['arabic', /[؀-ۿ]/g],
+  ['hebrew', /[֐-׿]/g],
+  ['thai', /[฀-๿]/g],
+  ['devanagari', /[ऀ-ॿ]/g],
+  ['latin', /[A-Za-zÀ-ɏ]/g],
+];
+
+const SCRIPT_LANGUAGE = {
+  hangul: 'ko',
+  greek: 'el',
+  arabic: 'ar',
+  hebrew: 'he',
+  thai: 'th',
+  devanagari: 'hi',
+};
+
+// Letters that only (or overwhelmingly) occur in one language of a script.
+const LATIN_MARKERS = {
+  pl: /[łęąńśźż]/i,
+  cs: /[řěůťďň]/i,
+  tr: /[ğışİ]/,
+  pt: /[ãõ]/i,
+  es: /[ñ¿¡]/,
+  de: /[ß]/,
+  fr: /[œ]/i,
+  sv: /[å]/i,
+};
+
+// Frequent function words per language. Scored by whole-word hits; every
+// list has the same length so scores stay comparable.
+const STOPWORDS = {
+  en: ['the', 'and', 'is', 'to', 'of', 'that', 'you', 'with', 'for', 'this', 'are', 'it', 'not', 'have', 'can', 'will', 'your', 'from', 'which', 'when'],
+  de: ['und', 'der', 'die', 'das', 'ist', 'nicht', 'mit', 'ein', 'eine', 'auch', 'sich', 'auf', 'für', 'wird', 'werden', 'oder', 'aber', 'wenn', 'sind', 'kann'],
+  fr: ['le', 'la', 'les', 'et', 'est', 'une', 'des', 'pour', 'que', 'qui', 'dans', 'pas', 'vous', 'sur', 'avec', 'sont', 'nous', 'cette', 'mais', 'plus'],
+  es: ['el', 'la', 'los', 'las', 'que', 'es', 'una', 'por', 'para', 'con', 'del', 'como', 'pero', 'más', 'este', 'esta', 'son', 'tiene', 'puede', 'también'],
+  it: ['il', 'la', 'che', 'di', 'è', 'una', 'per', 'non', 'con', 'del', 'della', 'come', 'sono', 'anche', 'questo', 'questa', 'gli', 'nel', 'più', 'essere'],
+  pt: ['o', 'a', 'os', 'as', 'que', 'é', 'uma', 'para', 'com', 'não', 'do', 'da', 'como', 'mas', 'também', 'este', 'esta', 'são', 'você', 'pode'],
+  pl: ['i', 'nie', 'jest', 'się', 'na', 'to', 'że', 'jak', 'ale', 'dla', 'oraz', 'przez', 'czy', 'tym', 'jego', 'można', 'jeśli', 'tego', 'które', 'także'],
+  nl: ['de', 'het', 'een', 'en', 'van', 'is', 'niet', 'dat', 'met', 'voor', 'ook', 'zijn', 'maar', 'als', 'wordt', 'deze', 'kan', 'naar', 'bij', 'dan'],
+  cs: ['a', 'je', 'se', 'na', 'to', 'že', 'jak', 'ale', 'pro', 'nebo', 'jsou', 'může', 'také', 'tento', 'když', 'jeho', 'které', 'být', 'aby', 'ještě'],
+  tr: ['ve', 'bir', 'bu', 'için', 'ile', 'de', 'da', 'ama', 'gibi', 'daha', 'var', 'olarak', 'çok', 'ne', 'her', 'kadar', 'sonra', 'değil', 'olan', 'ise'],
+  sv: ['och', 'att', 'det', 'är', 'en', 'som', 'för', 'inte', 'med', 'till', 'den', 'kan', 'har', 'ett', 'men', 'också', 'eller', 'från', 'när', 'vara'],
+  uk: ['і', 'та', 'що', 'це', 'не', 'як', 'для', 'він', 'вона', 'але', 'або', 'також', 'тільки', 'вже', 'якщо', 'його', 'цей', 'ця', 'бути', 'коли'],
+  ru: ['и', 'что', 'это', 'не', 'как', 'для', 'он', 'она', 'но', 'или', 'также', 'только', 'уже', 'если', 'его', 'этот', 'эта', 'быть', 'когда', 'чтобы'],
+};
+
+const LATIN_LANGUAGES = ['en', 'de', 'fr', 'es', 'it', 'pt', 'pl', 'nl', 'cs', 'tr', 'sv'];
+const CYRILLIC_LANGUAGES = ['uk', 'ru'];
+
+const countMatches = (text, pattern) => {
+  const matches = text.match(pattern);
+  return matches ? matches.length : 0;
+};
+
+const scoreStopwords = (words, languages) => {
+  const scores = {};
+  for (const language of languages) {
+    const list = new Set(STOPWORDS[language]);
+    let hits = 0;
+    for (const word of words) {
+      if (list.has(word)) hits += 1;
+    }
+    scores[language] = hits;
+  }
+  return scores;
+};
+
+const bestOf = (scores, fallback) => {
+  let best = fallback;
+  let bestScore = 0;
+  for (const [language, score] of Object.entries(scores)) {
+    if (score > bestScore) {
+      best = language;
+      bestScore = score;
+    }
+  }
+  return best;
+};
+
+const pickByMarkers = (text, markers) => {
+  for (const [language, pattern] of Object.entries(markers)) {
+    if (pattern.test(text)) return language;
+  }
+  return null;
+};
+
+/**
+ * @param {string} text
+ * @returns {{ language: string, script: string }} BCP-47 primary language subtag and the dominant script.
+ */
+export function detectTextLanguage(text) {
+  const source = typeof text === 'string' ? text : '';
+  const counts = SCRIPT_RANGES.map(([script, pattern]) => [script, countMatches(source, pattern)]);
+  const letters = counts.reduce((sum, [, count]) => sum + count, 0);
+  if (letters === 0) return { language: 'en', script: 'latin' };
+
+  // Kana settles Japanese even when Han dominates the character count.
+  const kana = counts.find(([script]) => script === 'kana')?.[1] ?? 0;
+  const han = counts.find(([script]) => script === 'han')?.[1] ?? 0;
+  if (kana > 0 && kana + han >= letters * 0.3) return { language: 'ja', script: 'kana' };
+  if (han > 0 && han >= letters * 0.3) return { language: 'zh', script: 'han' };
+
+  const [script] = counts.reduce((best, entry) => (entry[1] > best[1] ? entry : best));
+
+  if (script in SCRIPT_LANGUAGE) return { language: SCRIPT_LANGUAGE[script], script };
+
+  const words = source.toLowerCase().split(/[^\p{L}\p{M}']+/u).filter(Boolean);
+
+  if (script === 'cyrillic') {
+    const scores = scoreStopwords(words, CYRILLIC_LANGUAGES);
+    const ukMarkers = countMatches(source, /[іїєґ]/gi);
+    const ruMarkers = countMatches(source, /[ыэъё]/gi);
+    // Letters decide: the two alphabets differ in letters that occur in
+    // nearly every sentence. Function words only settle a text that shows
+    // neither set, and a text with no Russian-only letters is far more
+    // likely Ukrainian than the reverse, so that tie goes to Ukrainian.
+    if (ukMarkers !== ruMarkers) return { language: ukMarkers > ruMarkers ? 'uk' : 'ru', script };
+    if (scores.uk !== scores.ru) return { language: scores.uk > scores.ru ? 'uk' : 'ru', script };
+    return { language: ruMarkers > 0 ? 'ru' : 'uk', script };
+  }
+
+  const scores = scoreStopwords(words, LATIN_LANGUAGES);
+  const marked = pickByMarkers(source, LATIN_MARKERS);
+  // A characteristic letter outranks stopword counts unless another language
+  // clearly dominates the function words (a German text quoting "façade").
+  if (marked && scores[marked] * 2 >= scores[bestOf(scores, marked)]) {
+    return { language: marked, script };
+  }
+  return { language: bestOf(scores, 'en'), script };
+}
+
+/**
+ * Map a detected language onto the locales a voice list uses (`uk_UA`,
+ * `en_US`...). Returns the preferred locale prefixes in order.
+ * @param {string} language
+ * @returns {string[]}
+ */
+function localePrefixesForLanguage(language) {
+  const table = {
+    en: ['en_US', 'en_GB', 'en'],
+    uk: ['uk_UA', 'uk'],
+    ru: ['ru_RU', 'ru'],
+    de: ['de_DE', 'de'],
+    fr: ['fr_FR', 'fr_CA', 'fr'],
+    es: ['es_ES', 'es_MX', 'es'],
+    it: ['it_IT', 'it'],
+    pt: ['pt_BR', 'pt_PT', 'pt'],
+    pl: ['pl_PL', 'pl'],
+    nl: ['nl_NL', 'nl_BE', 'nl'],
+    cs: ['cs_CZ', 'cs'],
+    tr: ['tr_TR', 'tr'],
+    sv: ['sv_SE', 'sv'],
+    zh: ['zh_CN', 'zh_TW', 'zh_HK', 'zh'],
+    ja: ['ja_JP', 'ja'],
+    ko: ['ko_KR', 'ko'],
+    el: ['el_GR', 'el'],
+    ar: ['ar_001', 'ar_SA', 'ar'],
+    he: ['he_IL', 'he'],
+    th: ['th_TH', 'th'],
+    hi: ['hi_IN', 'hi'],
+  };
+  return table[language] ?? [language];
+}
+
+/**
+ * Choose a voice for a language from a `say`-style voice list.
+ * Prefers an enhanced/premium variant of a matching voice, then any voice of
+ * the exact locale, then any voice of the language. Returns null when the
+ * list has no voice for that language.
+ * @param {string} language
+ * @param {ReadonlyArray<{ name: string, locale: string }>} voices
+ * @returns {string | null}
+ */
+export function pickVoiceForLanguage(language, voices) {
+  const prefixes = localePrefixesForLanguage(language);
+  for (const prefix of prefixes) {
+    const matching = voices.filter((voice) => voice.locale === prefix || voice.locale.startsWith(`${prefix}_`) || (prefix === language && voice.locale.startsWith(`${language}_`)));
+    if (matching.length === 0) continue;
+    const enhanced = matching.find((voice) => /\((Enhanced|Premium)\)/i.test(voice.name));
+    return (enhanced ?? matching[0]).name;
+  }
+  return null;
+}
+
+/**
+ * Language of a voice, from its locale (`uk_UA` → `uk`).
+ * @param {string | null | undefined} locale
+ * @returns {string | null}
+ */
+export function languageOfLocale(locale) {
+  if (typeof locale !== 'string' || !locale) return null;
+  return locale.split(/[_-]/)[0].toLowerCase();
+}

packages/web/server/lib/tts/language-detect.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { detectTextLanguage, languageOfLocale, pickVoiceForLanguage } from './language-detect.js';
+
+describe('detectTextLanguage', () => {
+  it.each([
+    ['en', 'The build is green and the tests pass, so you can merge this now.'],
+    ['uk', 'Привіт! Це тестове повідомлення, і воно написане українською мовою.'],
+    ['ru', 'Привет! Это тестовое сообщение, и оно написано на русском языке.'],
+    ['de', 'Die Änderung ist fertig und die Tests laufen ohne Fehler durch.'],
+    ['fr', 'La modification est prête et les tests passent sans erreur.'],
+    ['es', 'El cambio está listo y las pruebas pasan sin errores.'],
+    ['it', 'La modifica è pronta e i test passano senza errori.'],
+    ['pt', 'A alteração está pronta e os testes passam sem erros, você pode continuar.'],
+    ['pl', 'Zmiana jest gotowa i testy przechodzą bez błędów.'],
+    ['nl', 'De wijziging is klaar en de tests slagen zonder fouten.'],
+    ['cs', 'Změna je hotová a testy procházejí bez chyb.'],
+    ['tr', 'Değişiklik hazır ve testler hatasız geçiyor.'],
+    ['sv', 'Ändringen är klar och testerna går igenom utan fel.'],
+    ['zh', '修改已经完成，所有测试都通过了。'],
+    ['ja', '変更が完了し、すべてのテストに合格しました。'],
+    ['ko', '변경이 완료되었고 모든 테스트를 통과했습니다.'],
+  ])('detects %s', (language, text) => {
+    expect(detectTextLanguage(text).language).toBe(language);
+  });
+
+  it.each([
+    ['uk', 'Готово. Запушено.'],
+    ['uk', 'Все ок'],
+    ['uk', 'Добре, давай так зробимо'],
+    ['ru', 'Хорошо, давай так и сделаем'],
+    ['ru', 'Готово, всё запушено.'],
+  ])('tells short %s phrases apart by letters', (language, text) => {
+    expect(detectTextLanguage(text).language).toBe(language);
+  });
+
+  it('falls back to English for text without letters', () => {
+    expect(detectTextLanguage('1234 ... !!!').language).toBe('en');
+    expect(detectTextLanguage('').language).toBe('en');
+  });
+
+  it('does not let a single quoted foreign word flip an English paragraph', () => {
+    const text = 'The façade of the building is the part that you see from the street, and it is not the same as the interior.';
+    expect(detectTextLanguage(text).language).toBe('en');
+  });
+});
+
+describe('pickVoiceForLanguage', () => {
+  const voices = [
+    { name: 'Samantha', locale: 'en_US' },
+    { name: 'Daniel', locale: 'en_GB' },
+    { name: 'Lesya', locale: 'uk_UA' },
+    { name: 'Lesya (Enhanced)', locale: 'uk_UA' },
+    { name: 'Milena', locale: 'ru_RU' },
+    { name: 'Anna', locale: 'de_DE' },
+  ];
+
+  it('prefers the enhanced variant of a matching voice', () => {
+    expect(pickVoiceForLanguage('uk', voices)).toBe('Lesya (Enhanced)');
+  });
+
+  it('prefers the primary locale of a language', () => {
+    expect(pickVoiceForLanguage('en', voices)).toBe('Samantha');
+  });
+
+  it('returns null when no voice speaks the language', () => {
+    expect(pickVoiceForLanguage('ja', voices)).toBeNull();
+  });
+});
+
+describe('languageOfLocale', () => {
+  it('reads the language subtag', () => {
+    expect(languageOfLocale('uk_UA')).toBe('uk');
+    expect(languageOfLocale('en-GB')).toBe('en');
+    expect(languageOfLocale(null)).toBeNull();
+  });
+});

packages/web/server/lib/tts/routes.js

@@ -2,6 +2,8 @@ import express from 'express';
 import { normalizeCustomOpenAIBaseURL } from './base-url.js';
 import { summarizeText, sanitizeForTTS, sanitizeForNote } from '../text/summarization.js';
 
+import { detectTextLanguage, languageOfLocale, pickVoiceForLanguage } from './language-detect.js';
+
 export function registerTtsRoutes(app, { sayTTSCapability }) {
   let ttsModulePromise = null;
   const getTtsModule = async () => {
@@ -154,7 +156,8 @@ export function registerTtsRoutes(app, { sayTTSCapability }) {
   // macOS 'say' command TTS speak endpoint
   app.post('/api/tts/say/speak', async (req, res) => {
     try {
-      const { text, voice = 'Samantha', rate = 200 } = req.body || {};
+      const { text, rate = 200, language, languageSample } = req.body || {};
+      let voice = typeof req.body?.voice === 'string' && req.body.voice.trim() ? req.body.voice.trim() : 'Samantha';
       
       if (!text || typeof text !== 'string' || !text.trim()) {
         return res.status(400).json({ error: 'Text is required' });
@@ -164,6 +167,23 @@ export function registerTtsRoutes(app, { sayTTSCapability }) {
       if (process.platform !== 'darwin') {
         return res.status(503).json({ error: 'macOS say command not available on this platform' });
       }
+
+      // `language: 'auto'`: keep the chosen voice while it speaks the text's
+      // language, otherwise switch to an installed voice that does. A
+      // language with no installed voice keeps the chosen voice — say still
+      // reads the text, just with an accent — rather than failing.
+      let resolvedLanguage = null;
+      if (language === 'auto') {
+        const capability = await sayTTSCapability;
+        const voices = Array.isArray(capability?.voices) ? capability.voices : [];
+        const sample = typeof languageSample === 'string' && languageSample.trim() ? languageSample.slice(0, 4000) : text;
+        resolvedLanguage = detectTextLanguage(sample).language;
+        const chosen = voices.find((entry) => entry.name === voice);
+        if (languageOfLocale(chosen?.locale) !== resolvedLanguage) {
+          const match = pickVoiceForLanguage(resolvedLanguage, voices);
+          if (match) voice = match;
+        }
+      }
       
       const { exec } = await import('child_process');
       const { promisify } = await import('util');
@@ -195,6 +215,8 @@ export function registerTtsRoutes(app, { sayTTSCapability }) {
       
       // Send audio response
       res.setHeader('Content-Type', 'audio/mp4');
+      res.setHeader('X-Speech-Voice', voice);
+      if (resolvedLanguage) res.setHeader('X-Speech-Language', resolvedLanguage);
       res.setHeader('Content-Length', audioBuffer.length);
       res.send(audioBuffer);
       

packages/web/server/lib/tts/routes.test.js

@@ -33,6 +33,32 @@ describe('tts routes', () => {
     });
   });
 
+  it('switches the say voice to the language of the text when asked to', async () => {
+    const capability = Promise.resolve({
+      available: true,
+      voices: [
+        { name: 'Samantha', locale: 'en_US' },
+        { name: 'Lesya', locale: 'uk_UA' },
+        { name: 'Lesya (Enhanced)', locale: 'uk_UA' },
+      ],
+    });
+    const app = createApp(capability);
+    const response = await request(app)
+      .post('/api/tts/say/speak')
+      .send({ text: 'Привіт! Це відповідь українською мовою, і вона досить довга.', voice: 'Samantha', language: 'auto' });
+
+    // On macOS the route synthesizes; elsewhere it refuses before running say.
+    // Either way the chosen voice must be the Ukrainian one when the platform
+    // allows the request to proceed.
+    if (process.platform === 'darwin') {
+      expect(response.status).toBe(200);
+      expect(response.headers['x-speech-voice']).toBe('Lesya (Enhanced)');
+      expect(response.headers['x-speech-language']).toBe('uk');
+    } else {
+      expect(response.status).toBe(503);
+    }
+  });
+
   it('returns local note fallback while model summarization is retired', async () => {
     const response = await request(createApp())
       .post('/api/text/summarize')