One voice per listener, and the voice process stops stalling itself

Build 127. Reported from a live test: part of the translation came out in a different voice on an Android phone, and iPhones were skipping and repeating. Three investigations against the campus Mac's own log and transcript, one test harness driving the voice process directly, and the answer is not what it sounded like. WHAT THE MACHINE DID. One voice process ran all afternoon. Every language kept a single resident engine from its first sentence (14:54:26) to STOP (15:23:18); 2,800 clips, 560 per language, every one filed under its own language and spoken by its own bundle. No synthesis-side voice change was possible with that configuration. What the log shows at the time of the complaint instead: - Someone on the English stream heard the ROOM MICROPHONE for 21 s (15:09:10-32). English was the first button on every phone's list, forced there by the page whatever the operator had chosen (fixed in build 125). - A listener tapped Chinese at 15:11:17. The 121 MB zh model was fetched and unpacked THREE TIMES AT ONCE on the voice process's only thread. Every stream stalled for about a minute, 26 sentences were dropped across all five languages, and the catch-up rushed the Spanish voices to their +16% cap. Same voice, sounding wrong. WHAT WAS WRONG, AND IS NOW FIXED. The live path filed every engine as an "audition". speak() resolved the language's default voice, which always has a bundle, and passed it as `explicit`, so the key was 'audition:'+bundle for every ordinary sentence while the preload warmed copies under the language name that no sentence ever read. Five languages asked for nine engines against a cap of six; every service's first sentence built its real engines on the spot (1.3-2 s); the operator's voice save flushed nothing that mattered. Engines are now keyed by bundle and shared by every language, variant and audition that uses one, auditions take at most two slots of their own and can never evict a live engine, and the cap is 8, sized to the largest campus from measurement (~165 MB per engine once it has spoken, 1.3 GB for eight). Voice installs ran on the thread that answers every sentence, and were not de-duplicated. They now run in a worker thread (voice-install.js), one per bundle however many ask, staged and renamed into place whole so a half- written bundle can never pass isInstalled(). Listener rows are { code, count } and engine.js read { lang, n } in five places, so the set of "languages someone is on" was always empty — and a late sentence keeps speech only for those. Under load the app dropped EVERY language's speech instead of only the unchosen ones. Late became silent. HLS segment numbers restarted at 1 for every new stream object, under a 'max-age=60, immutable' header. A phone back from the lock screen could be answered from its cache with the previous stream's audio under the new number: an earlier sentence, replayed. Numbers are seeded from the clock. In clips mode a clip still downloading when the listener switched language landed and played in the voice they had left; the frame now carries its language and voice and the page checks both when the bytes land. In stream mode the old playlist stayed loaded through a switch and three things could restart it; it is stopped, not paused. A listener's alternate voice no longer loses a round trip to the default on the original-text toggle. One genuine wrong-voice path, dormant today because natural voices are off on this campus: a variant waiting on another variant's premium synthesis inherited that variant's Piper FALLBACK, in that variant's bundle — spa_ES received the byte-identical Mexican clip and its own voice never loaded. A follower now shares a fallback only when it is its own voice. An audition (the Voices card's play button) played on the system default output, which on the campus Mac is the Dante card feeding the hardware channels. It now plays on another output, or refuses and says why. VERIFIED: a harness drives the voice process through the baseline, a batch of four auditions during live sentences, a voices save mid-stream, and nine live languages against the cache — every clip spoken by its own bundle, and auditions of a live voice now cost 78-311 ms with nothing rebuilt. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-15 16:05:15 -04:00
7 changed files with 426 additions and 110 deletions
@@ -195,6 +195,23 @@ const state = {
  degradedAt: 0
 };

+/*
+ * THE SHAPE OF A LISTENER ROW. The server sends { code, count } — see
+ * listenerCounts() in server.js — and this file read { lang, n } in five
+ * places, so every set built from the rows was EMPTY: no language ever counted
+ * as being listened to. Mostly harmless, except in the one place it mattered.
+ * When a sentence arrives late, speech is kept only for the languages someone
+ * is actually on, and "someone is on" was never true for any of them — so
+ * under load the app dropped the speech of EVERY language, for everyone,
+ * instead of only the languages nobody had chosen. Late became silent.
+ * MEASURED on a campus Mac, 2026-10-15 15:11-15:12: 26 sentences dropped
+ * across five languages during a stall, every one of them with listeners
+ * present. Both spellings are read, so a server one build older or newer
+ * still counts.
+ */
+function rowLang(r)  { return r ? (r.code || r.lang || '') : ''; }
+function rowCount(r) { return r ? (Number(r.count != null ? r.count : r.n) || 0) : 0; }
+
 /*
 * FOLLOW THE BOTTOM ONLY WHILE THE OPERATOR IS AT THE BOTTOM.
 *
@@ -1070,10 +1087,15 @@ function preloadNewVoices() {
  const want = state.targets.filter((l) =>
    state.spokenLanguages.indexOf(l) !== -1 && !preloadedVoices.has(l));
  if (!want.length) return;
-  want.forEach((l) => preloadedVoices.add(l));
  /* One at a time in the child anyway; cap the request so a burst of joins
-     cannot queue up a re-download marathon. */
-  window.engineHost.ttsPreload(want.slice(0, 4));
+     cannot queue up a re-download marathon.
+     Only what is SENT counts as warmed. Every wanted language used to be
+     marked and only the first four sent, so a fifth was never preloaded and
+     built its engine on its first sentence instead — por_PT, at all five
+     starts on the Mini on 2026-10-15. Six is the voice process's own cap. */
+  const batch = want.slice(0, 6);
+  batch.forEach((l) => preloadedVoices.add(l));
+  window.engineHost.ttsPreload(batch);
 }

 /* The translation model reports its download from the main process. */
@@ -1084,7 +1106,10 @@ if (window.engineHost && window.engineHost.onTtsReady) {
    state.spokenDefaults = info.defaults || state.spokenDefaults || {};
    log('built-in voices ready — ' + state.spokenLanguages.length + ' languages', 'ok');
    /* Warm whatever people are already reading, so the first sentence of a
-       service is not the one that pays for the download. */
+       service is not the one that pays for the download. A voice process
+       that has just (re)started holds no engines, whatever this page warmed
+       in the last one — so forget that first. */
+    preloadedVoices.clear();
    preloadNewVoices();
  });
  window.engineHost.onTtsProgress((p) => log('voice ' + p.bundle + ': ' + p.status));
@@ -1778,9 +1803,9 @@ async function pumpPartial() {
     * still gets a preview.
     */
    const heard = (state.byLanguage || [])
-      .filter((r) => r && r.lang && r.lang !== state.source && (r.n || 0) > 0)
+      .filter((r) => r && rowLang(r) && rowLang(r) !== state.source && rowCount(r) > 0)
      .sort((a, b) => (b.n || 0) - (a.n || 0))
-      .map((r) => r.lang)
+      .map(rowLang)
      .filter((l) => state.targets.indexOf(l) !== -1);
    const want = (heard.length ? heard : orderedTargets()).slice(0, PARTIAL_MAX_LANGS);
    /* Never queue behind a finished sentence — a final in flight is worth more
@@ -1806,7 +1831,7 @@ async function pumpPartial() {
 */
 function orderedTargets() {
  const counts = {};
-  for (const row of state.byLanguage || []) counts[row.lang] = row.n || 1;
+  for (const row of state.byLanguage || []) counts[rowLang(row)] = rowCount(row) || 1;
  return state.targets
    .filter((t) => t !== state.source)
    .sort((a, b) => (counts[b] || 0) - (counts[a] || 0));
@@ -1969,7 +1994,7 @@ async function pump() {
        /* Late, but nothing is behind it: say so, and translate it anyway. */
        log('audio ' + ageSec.toFixed(0) + 's late, but nothing is queued — translating it anyway', 'warn');
      } else if (ageSec > 6) {
-        const listening = new Set((state.byLanguage || []).map((r) => r.lang));
+        const listening = new Set((state.byLanguage || []).map(rowLang));
        const before = targets.length;
        targets = targets.filter((t) => listening.has(t));
        if (targets.length < before) { state.degradedFinals++; state.degradedAt = Date.now(); }
@@ -2169,7 +2194,7 @@ setInterval(() => {
 }, 30000);

 function translateSentence(cid, sentence, targets, gainDb, silent) {
-  const listening = new Set((state.byLanguage || []).map((r) => r.lang));
+  const listening = new Set((state.byLanguage || []).map(rowLang));
  for (const lang of targets) {
    if ((mtDepth[lang] || 0) > 6 && !listening.has(lang)) {
      state.degradedFinals++;
@@ -4643,6 +4668,40 @@ function renderVoiceList() {
  }
 }

+/*
+ * WHERE AN AUDITION PLAYS: never on the card that feeds the room.
+ *
+ * An <audio> element with no sink plays on the system default output, and on
+ * the production Mini that IS the Dante Virtual Soundcard (system_profiler:
+ * "Default Output Device: Yes") — the same card that carries Spanish on its
+ * third channel (outputMap spa_Latn -> [2]). So ▶ there put the sample line
+ * onto the Dante network, service or no service. The phones were never
+ * exposed: an audition comes back to this page as bytes and never becomes a
+ * clip the server can see.
+ *
+ * Which of the card's channels it reached is Chromium's mono up-mix and the
+ * Dante routing, neither of which this page controls, so it does not try to
+ * pick a "safe" channel. It plays on another output, or not at all, and says
+ * why.
+ */
+async function auditionSink() {
+  const routedId = ($('outDevice') && $('outDevice').value) || '';
+  const routedLabel = (state.cfg && state.cfg.outputDeviceLabel) || '';
+  if (!routedId && !routedLabel) return '';           // no hardware output in use
+  const strip = (l) => String(l || '').toLowerCase().replace(/^default\s*-\s*/, '').trim();
+  let outs = [];
+  try {
+    outs = (await navigator.mediaDevices.enumerateDevices()).filter((d) => d.kind === 'audiooutput');
+  } catch (_) { /* refused below rather than guessed */ }
+  const card = strip(((outs.find((d) => d.deviceId === routedId) || {}).label) || routedLabel);
+  const isCard = (d) => (!!routedId && d.deviceId === routedId) || (!!card && strip(d.label) === card);
+  const def = outs.find((d) => d.deviceId === 'default');
+  if (def && !isCard(def)) return '';                 // the system default is somewhere else
+  const other = outs.find((d) => d.deviceId !== 'default' && d.deviceId !== 'communications' && !isCard(d));
+  if (other) return other.deviceId;
+  throw new Error('the only output here is the one feeding the hardware channels — auditions stay off it');
+}
+
 async function auditionVoice(lang, v, btn, msg) {
  if (auditionBusy) return;
  auditionBusy = true;
@@ -4667,9 +4726,14 @@ async function auditionVoice(lang, v, btn, msg) {
      msg.className = 'vmsg';
    }
    if (instruct) msg.textContent = 'with your direction…';
+    /* Where it will play is settled BEFORE the voice process builds anything:
+       an audition that cannot play should cost the service nothing. */
+    const sink = await auditionSink();
    const out = await window.engineHost.ttsAudition({ lang, voice: v, instruct });
    if (!auditionAudio) auditionAudio = new Audio();
    if (!out.wav) throw new Error('that voice produced no audio');
+    if (typeof auditionAudio.setSinkId === 'function') await auditionAudio.setSinkId(sink);
+    else if (sink) throw new Error('this build cannot keep auditions off the hardware output');
    auditionAudio.src = 'data:audio/wav;base64,' + out.wav;
    /* play() rejects on autoplay policy or a decode failure; either way the
       operator needs the reason, not a silent button. */
@@ -2,7 +2,7 @@
  "name": "church-translate-engine",
  "productName": "Church Translate",
  "version": "3.23.2",
-  "buildNumber": 126,
+  "buildNumber": 127,
  "private": true,
  "description": "Live sermon translation — self-contained: captures audio, transcribes, translates, and serves the congregation page itself",
  "main": "main.js",
@@ -50,6 +50,7 @@
      "vendor/ort-wasm-simd-threaded.jsep.mjs",
      "server/**/*",
      "tts-service.js",
+      "voice-install.js",
      "kokoro-sidecar.js",
      "voices.js",
      "pt-variants.js",
@@ -106,7 +107,7 @@
      ]
    },
    "asar": false,
-    "buildVersion": "126",
+    "buildVersion": "127",
    "win": {
      "target": [
        {
@@ -219,7 +219,21 @@ class LanguageStream {
    this.dropTimes = [];      // when, for a "recently" view on the operator page
    this.building = [];       // frames of the segment being filled
    this.segments = [];       // { seq, body, frames }
-    this.nextSeq = 1;
+    /*
+     * SEGMENT NUMBERS MUST NEVER REPEAT, and starting at 1 made them repeat.
+     * A stream object is built when a language's first listener arrives and
+     * dropped when the last one leaves, so within one service the same
+     * language can get a fresh stream several times — and a phone that came
+     * back from the lock screen, or a second listener, asked for
+     * spa_Latn/1.aac again. The segments are served 'max-age=60, immutable',
+     * which is the right header for a segment that is never reused and the
+     * wrong one for a number that is: for up to a minute the browser answered
+     * from its cache with the PREVIOUS stream's audio under the new number —
+     * a sentence from earlier in the sermon, replayed. Numbering from the
+     * clock makes every incarnation's numbers new; HLS only asks that they
+     * increase by one within a playlist, which they still do.
+     */
+    this.nextSeq = Date.now();
    this.timer = null;
    this.lastTick = 0;
    this.carry = 0;           // fractional frames owed from the last tick
@@ -475,6 +475,7 @@
    drift: null,
    watchdog: null,       // catches engines that stall on HLS without erroring
    everPlayed: false,    // this engine has PROVEN it can play HLS
+    clipsForVoice: false, // on clips because of an alternate voice, not because HLS failed
    // clip-fallback state
    ctx: null,
    keepAlive: null,
@@ -594,9 +595,13 @@
  /* Give up on streaming and use per-sentence clips. The clip path was already
     unlocked inside the tap precisely so this is possible after the gesture has
     been spent — otherwise a browser that lies about HLS would end up silent. */
-  function fallBackToClips() {
+  function fallBackToClips(forVoice) {
    if (srv.mode === 'clips') return;
    srv.mode = 'clips';
+    /* Remember WHY. Only a page that left the stream for an alternate voice
+       returns to it when the listener goes back to the default — see
+       applyVoiceMode(). */
+    srv.clipsForVoice = !!forVoice;
    stopStream();
    if (srv.keepAlive) srv.keepAlive.play().catch(function () {});
    try { console.warn('live stream unsupported here — using per-sentence clips'); } catch (_) {}
@@ -868,14 +873,27 @@
   */
  function applyVoiceMode() {
    if (srv.voice) {
-      fallBackToClips();
+      fallBackToClips(true);
      return;
    }
    /* Back on the default: allow streaming again. fallBackToClips latches
       mode to 'clips' and maybeStartStream refuses to act on that, so the
       latch has to be released here or the listener stays on clips for the
       rest of the service. */
-    if (srv.mode === 'clips' && hlsSupported() && srv.unlocked && srv.serverHello) {
+    /*
+     * Only when the alternate is what put us on clips. Every engine reconnect
+     * sends every listener a 'voices' frame, and an engine that cannot play
+     * HLS used to be handed back to the stream by it — eight seconds of
+     * dropped clips until the watchdog demoted it again.
+     *
+     * And silence the alternate's clips that are still scheduled. Left to
+     * play out they overlapped the shared stream as it came up: the voice
+     * the listener left and the default together, for up to the six seconds
+     * the clip queue holds.
+     */
+    if (srv.mode === 'clips' && srv.clipsForVoice && hlsSupported() && srv.unlocked && srv.serverHello) {
+      stopClips();
+      srv.clipsForVoice = false;
      srv.mode = '';
      maybeStartStream();
    }
@@ -909,22 +927,52 @@
  function switchAudioLanguage(lang) {
    stopClips();                       // the old language stops NOW, mid-word
    if (srv.mode === 'stream' && srv.el) {
-      /* Pause the old stream; the new one starts when the server's hello
-         confirms the new language's stream exists. */
-      try { srv.el.pause(); } catch (_) {}
-      if (srv.retry) { clearTimeout(srv.retry); srv.retry = null; }
+      /*
+       * STOP the old stream, do not merely pause it; the new one starts when
+       * the server's hello confirms the new language's stream exists.
+       *
+       * Paused, the element still pointed at the OLD playlist until that
+       * hello, and three things restart a paused element without asking: the
+       * 8 s watchdog's retry (startStream(srv.lang, true), and srv.lang was
+       * still the old language), coming back from a locked screen
+       * (visibilitychange plays it), and the lock-screen play button. Each
+       * put the previous language's voice back in the listener's ear.
+       * stopStream() is what the back button already does, and the hello's
+       * maybeStartStream() brings the new language up from it.
+       */
+      stopStream();
    }
    setMediaSession();
  }

  // ------------------------------------------------- per-clip fallback path

+  /*
+   * Is this clip for the language AND voice this page is on right now?
+   *
+   * Asked twice — when the clip is announced and again when its bytes land —
+   * because the fetch and the decode take a few hundred milliseconds, and
+   * stopClips() can only silence what is already scheduled, not what is still
+   * downloading. A listener who switched language in that window heard the
+   * previous language's sentence AFTER the switch; for Spanish that is one
+   * sentence of the Mexican voice in a Spaniard's ear, or the reverse. The
+   * name carries the language (p<seq>-spa_ES.aac); the server also sends lang
+   * and voice in the frame, and a frame without them is judged on the name.
+   */
+  function clipIsOurs(frame) {
+    var lang = frame.lang || (String(frame.name).match(/-([a-z]{3}_[A-Za-z]+)\.aac$/) || [])[1];
+    if (lang !== app.lang) return false;
+    if ('voice' in frame && String(frame.voice || '') !== String(srv.voice || '')) return false;
+    return true;
+  }
+
  /* Fetch, decode and schedule one clip so it follows the previous one. Only
     used where native HLS is missing. */
  function playClip(frame) {
    var name = frame && frame.name;
    if (srv.mode === 'stream') return;      // the stream already carries it
    if (!tts.on || !srv.ctx || !name) return;
+    if (!clipIsOurs(frame)) return;

    fetch('/audio/' + encodeURIComponent(name))
      .then(function (r) { return r.ok ? r.arrayBuffer() : Promise.reject(new Error('missing')); })
@@ -936,6 +984,8 @@
      })
      .then(function (audio) {
        if (!tts.on || !srv.ctx) return;
+        /* Landed after a switch of language, voice or mode: not ours any more. */
+        if (srv.mode === 'stream' || !clipIsOurs(frame)) return;
        var src = srv.ctx.createBufferSource();
        src.buffer = audio;
        src.connect(srv.ctx.destination);
@@ -1424,7 +1474,11 @@
        }
        /* The playlist is guaranteed to exist from this moment — the server
           creates the stream when this listener registers. */
-        maybeStartStream();
+        /* Not for a listener on an alternate: the shared stream is the
+           operator's default voice, and starting it here played that voice
+           until the server's 'voices' reply moved the page to clips. */
+        if (srv.voice) fallBackToClips(true);
+        else maybeStartStream();
        /* The picker was rendered before this socket existed, when we still had
           to assume the device's own voice. Now we know better — re-render, or
           a listener keeps staring at a voice chooser that controls nothing. */
@@ -1763,12 +1763,20 @@ wss.on('connection', (ws, req) => {
        if (!m.voice) row.audio[m.lang] = m.name;

        delayed((who) => {
-          const frame = JSON.stringify({
-            t: 'audio', id: row.id, name: m.name, seconds: m.seconds || 0
-          });
          /* Which voice this clip IS. '' is the operator's default, which is
             what a listener who never opened the chooser is on. */
          const clipVoice = String(m.voice || '');
+          /*
+           * The frame says which language and voice it carries, and the page
+           * checks both again when the clip's bytes land (clipIsOurs() in
+           * listen.js). The routing below is decided at SEND time; a listener
+           * who switches language or voice while a clip is still downloading
+           * would otherwise hear it after the switch, in the voice they left.
+           */
+          const frame = JSON.stringify({
+            t: 'audio', id: row.id, name: m.name, seconds: m.seconds || 0,
+            lang: m.lang, voice: clipVoice
+          });
          for (const [ws, meta] of state.listeners) {
            if (ws.readyState !== 1) continue;
            if (!who(meta)) continue;
@@ -2054,14 +2062,22 @@ wss.on('connection', (ws, req) => {
    if (m.t === 'lang') {
      const meta = state.listeners.get(ws);
      if (!meta) return;
-      meta.lang = String(m.lang || config.sourceLanguage);
+      const next = String(m.lang || config.sourceLanguage);
      /*
       * A voice belongs to a language. Carrying a Spanish speaker across to
       * Portuguese would ask the engine for a voice that language does not
       * have, so switching language always returns the listener to the
       * default and hands them the new language's options.
+       *
+       * Only a CHANGE of language, though. The page re-sends the language it
+       * is already on to have its captions re-rendered (the original-text
+       * toggle does exactly that), and resetting the voice there put a
+       * listener on an alternate back on the default for a round trip —
+       * until the page re-asserted its pick, they were sent the default
+       * voice's clips: one voice, then the other, then theirs again.
       */
-      meta.voice = '';
+      if (next !== meta.lang) meta.voice = '';
+      meta.lang = next;
      pushLanguagesToEngine();
      /*
       * builtInVoice MUST be here, not just on the first hello. The page does
@@ -2073,7 +2089,7 @@ wss.on('connection', (ws, req) => {
       */
      send(ws, { t: 'hello', live: state.live, lang: meta.lang, serviceName: config.serviceName, build: BUILD,
                 builtInVoice: Voices.hasVoice(meta.lang),
-                 voiceOptions: voiceOptionsFor(meta.lang), voice: '',
+                 voiceOptions: voiceOptionsFor(meta.lang), voice: meta.voice || '',
                 scrollback: scrollbackFor(meta.lang, meta.proxied) });
      broadcastOperators();
    }
@@ -42,9 +42,6 @@ let VOICE_DIR = process.platform === 'win32'
  : path.join(os.homedir(), 'Library/Application Support/Church Translate Voices');
 let CLIP_DIR = path.join(os.tmpdir(), 'church-translate-audio');

-/* Loaded engines, one per language. Kept small: each costs ~330-400 MB of ONNX
-   arena regardless of the 63 MB model, so we do not hold voices nobody is
-   listening to. */
 /* What each voice says when auditioned — a real line of scripture, so the
   operator hears the voice on the material it will actually read. */
 const SAMPLE_TEXT = {
@@ -65,8 +62,25 @@ const SAMPLE_TEXT = {
  hat_Latn: 'Senyè a se gadò mwen, mwen p ap manke anyen.'
 };

-const loaded = new Map();
-const MAX_LOADED = 6;
+/*
+ * Loaded engines, ONE PER BUNDLE, shared by every language, variant and
+ * audition that speaks with it. Kept bounded, not small: MEASURED on an M2
+ * Max, an engine costs ~75 MB at construction and ~165 MB once it has spoken
+ * (8 engines, 1.3 GB after one sentence each), not the 330-400 MB this used
+ * to assume. The cap is sized to the largest campus — eight languages — so a
+ * live engine is never evicted to make room for another live one in normal
+ * service; below the cap an eviction means a reload of ~0.3-0.5 s on this
+ * process's only thread, in front of the next sentence, every time.
+ *
+ * `live` marks an engine a sentence or the preload asked for. Auditions keep
+ * to MAX_AUDITION slots of their own, always go first, and can never push a
+ * live engine out: with every slot speaking, an auditioned voice is built,
+ * played once and dropped. See engineFor() for why this is keyed by bundle.
+ */
+const loaded = new Map();          // 'bundle/model' -> { tts, usedAt, live }
+const installing = new Map();      // bundle -> Promise: one download, however many ask
+const MAX_LOADED = 8;
+const MAX_AUDITION = 2;

 /*
 * The operator's per-language voice choices, made by ear in the Voices
@@ -142,81 +156,120 @@ function isInstalled(v) {
 * 359 files, same total bytes — and it is now the same code on both platforms.
 */
 function installVoice(v) {
+  /*
+   * OFF THIS THREAD. The fetch, the bzip2 and the unpack all ran here, on the
+   * voice process's only thread, from inside engineFor() — so the first
+   * sentence of a language whose voice was not installed yet stalled every
+   * OTHER language's sentences for as long as the install took. MEASURED on a
+   * campus Mac, 2026-10-15 15:11: a listener tapped Chinese, the 121 MB zh
+   * model was fetched and unpacked three times at once on this thread, every
+   * stream stalled, 26 sentences were dropped and the catch-up rushed the
+   * Spanish voices to their +16% cap. The work now happens in a worker thread
+   * (voice-install.js); this thread only relays its progress and keeps
+   * speaking. The worker unpacks into a staging folder and renames it into
+   * place whole, so isInstalled() never sees a half-written bundle.
+   */
  return new Promise((resolve, reject) => {
-    fs.mkdirSync(VOICE_DIR, { recursive: true });
-    const url = voices.bundleUrl(v.bundle);
-
+    const fail = (why) => reject(new Error('could not install ' + v.bundle + ': ' + why));
    reply({ type: 'voiceProgress', bundle: v.bundle, status: 'downloading' });
-
-    (async () => {
-      const res = await fetch(url, { redirect: 'follow' });
-      if (!res.ok) throw new Error('HTTP ' + res.status);
-      const body = Buffer.from(await res.arrayBuffer());
-      /* A proxy or a captive portal returns an HTML error page with HTTP 200;
-         the bzip2 magic is the cheapest way to notice before unpacking it. */
-      if (body.length < 1024 || body.toString('latin1', 0, 3) !== 'BZh') {
-        throw new Error('that download was not a voice bundle');
-      }
-      reply({ type: 'voiceProgress', bundle: v.bundle, status: 'installing' });
-
-      const bunzip = require('unbzip2-stream');
-      const tar = require('tar-stream');
-      const { Readable } = require('stream');
-
-      await new Promise((res2, rej2) => {
-        const extract = tar.extract();
-        extract.on('entry', (header, stream, next) => {
-          /* Never write outside VOICE_DIR, whatever the archive claims. */
-          const dest = path.resolve(VOICE_DIR, header.name);
-          if (dest !== VOICE_DIR && !dest.startsWith(VOICE_DIR + path.sep)) {
-            stream.resume(); return next();
-          }
-          if (header.type === 'directory') {
-            fs.mkdirSync(dest, { recursive: true });
-            stream.resume(); return next();
-          }
-          fs.mkdirSync(path.dirname(dest), { recursive: true });
-          stream.pipe(fs.createWriteStream(dest)).on('finish', next).on('error', rej2);
+    let w;
+    try {
+      const { Worker } = require('worker_threads');
+      w = new Worker(path.join(__dirname, 'voice-install.js'), {
+        workerData: { url: voices.bundleUrl(v.bundle), voiceDir: VOICE_DIR, bundle: v.bundle }
      });
-        extract.on('finish', res2);
-        extract.on('error', rej2);
-        Readable.from(body).pipe(bunzip()).on('error', rej2).pipe(extract);
+    } catch (e) { return fail(e.message); }
+    let settled = false;
+    const done = (err) => { if (settled) return; settled = true; err ? fail(err) : resolve(); };
+    w.on('message', (m) => {
+      if (!m || !m.status) return;
+      if (m.status === 'error') { done(m.message || 'the installer failed'); return; }
+      reply({ type: 'voiceProgress', bundle: v.bundle, status: m.status });
+      if (m.status === 'ready') done();
    });
-
-      reply({ type: 'voiceProgress', bundle: v.bundle, status: 'ready' });
-    })().then(resolve, (err) => reject(new Error('could not install ' + v.bundle + ': ' + err.message)));
+    w.on('error', (e) => done((e && e.message) || String(e)));
+    w.on('exit', (code) => { if (!settled) done('the installer exited (' + code + ')'); });
  });
 }

-async function engineFor(lang, explicit) {
-  /* Auditions key the cache by bundle so trying five voices for one language
-     does not evict the voice that language is actually using. */
-  const v = explicit || builtinVoiceFor(lang);
-  const key = explicit ? "audition:" + v.bundle : lang;
-  if (loaded.has(key)) {
-    const e = loaded.get(key);
+/*
+ * The engine for one voice, built at most once however many ask for it.
+ *
+ * KEYED BY BUNDLE — and the old keying is what put batches of four
+ * "audition:" loads in the production log with nobody at the Voices card.
+ * Engines were keyed two ways: by language ('spa_Latn') for the preload, and
+ * 'audition:<bundle>' whenever a voice was passed in, which speak() did for
+ * EVERY ordinary sentence because the resolved default always has a bundle.
+ * So the live path was filed as an audition, every bundle was built at least
+ * twice (five languages asked for nine engines against a cap of six), the
+ * preload warmed copies no sentence ever read, and the first sentence of
+ * every service built the real ones on the spot. MEASURED on the Mini,
+ * 2026-10-15: the 14:26 service's first sentence was said at 14:54:26.291
+ * and its four engines were ready at 26.995, 27.309, 27.833 and 28.344 —
+ * ~0.3-0.5 s each on this process's only thread — while what got evicted
+ * was the startup preload's unused copies.
+ *
+ * The engine's config is a function of the bundle alone (voices.ttsConfig;
+ * speed, gain and sid are applied per sentence), so sharing is exact:
+ * spa_Latn and spa_MX read one es_MX-ald engine, and auditioning a voice that
+ * is already speaking reads the live engine instead of building a second.
+ */
+async function engineFor(v, live, who) {
+  if (!v || !v.bundle) throw new Error('no built-in voice' + (who ? ' for ' + who : ''));
+  const key = v.bundle + '/' + (v.model || '');
+
+  /*
+   * One download per bundle. A language joining mid-service is asked for by
+   * the preload AND by its first sentences at once, and each used to fetch
+   * and unpack the whole bundle itself — MEASURED on the Mini: pt_BR-jeff
+   * three times between 11:39:05 and 11:39:50, zh-ll three times between
+   * 15:11:17 and 15:12:16, two 'voice timed out' each time. The unpack is staged and
+   * renamed into place whole (voice-install.js), so isInstalled() stays false
+   * until the bundle is complete — but a second asker must still wait on the
+   * first install, not start its own.
+   */
+  if (!loaded.has(key) && (installing.has(v.bundle) || !isInstalled(v))) {
+    if (!installing.has(v.bundle)) {
+      installing.set(v.bundle, installVoice(v).finally(() => installing.delete(v.bundle)));
+    }
+    await installing.get(v.bundle);
+  }
+
+  /* Looked up again: whoever finished waiting first has built it. Nothing can
+     interleave from here to the set — construction is synchronous. */
+  let e = loaded.get(key);
+  if (!e) {
+    if (!sherpa) sherpa = require('sherpa-onnx-node');
+    e = { tts: new sherpa.OfflineTts(voices.ttsConfig(voicePath(v), v)), usedAt: 0, live: !!live };
+    if (makeRoom(!!live)) loaded.set(key, e);
+    log('voice ready: ' + v.bundle + (who ? ' for ' + who : '') +
+        (live ? '' : loaded.get(key) === e ? ' (audition)' : ' (audition, not kept: every slot is speaking)'));
+  }
  e.usedAt = Date.now();
+  /* An audition never demotes a live engine; a sentence promotes an auditioned one. */
+  if (live) e.live = true;
  return e.tts;
 }

-  if (!v) throw new Error('no built-in voice for ' + lang);
-  if (!isInstalled(v)) await installVoice(v);
-
-  if (!sherpa) sherpa = require('sherpa-onnx-node');
-
-  const dir = voicePath(v);
-  const tts = new sherpa.OfflineTts(voices.ttsConfig(dir, v));
-
-  /* Evict the least recently used rather than growing without bound. */
-  if (loaded.size >= MAX_LOADED) {
-    let oldest = null;
-    for (const [k, e] of loaded) if (!oldest || e.usedAt < loaded.get(oldest).usedAt) oldest = k;
-    if (oldest) { loaded.delete(oldest); log('evicted voice ' + oldest); }
-  }
-
-  loaded.set(key, { tts, usedAt: Date.now() });
-  log('voice ready: ' + key + ' (' + v.bundle + ')');
-  return tts;
+/*
+ * Room for one more engine, or false when an audition should not take one.
+ * Least recently used goes first, as before — auditioned engines before live
+ * ones, and a live engine only ever gives way to another live one.
+ */
+function makeRoom(live) {
+  const stalest = (wantLive) => {
+    let k = null;
+    for (const [key, x] of loaded) if (x.live === wantLive && (!k || x.usedAt < loaded.get(k).usedAt)) k = key;
+    return k;
+  };
+  const evict = (k) => { log('evicted voice ' + k + (loaded.get(k).live ? '' : ' (audition)')); loaded.delete(k); };
+  const auditions = Array.from(loaded.values()).filter((x) => !x.live).length;
+  if (!live && auditions >= MAX_AUDITION) evict(stalest(false));
+  if (loaded.size < MAX_LOADED) return true;
+  const k = stalest(false) || (live ? stalest(true) : null);
+  if (!k) return false;
+  evict(k);
+  return true;
 }

 // ------------------------------------------------------------- cloud voices
@@ -928,6 +981,9 @@ async function speak(job) {
    text, Math.round((Number(job.gainDb) || 0) * 2) / 2, pinRate
  ].join('\u0001');

+  /* Set when the leader's result was a Piper fallback in ANOTHER variant's
+     voice — this job then speaks its own fallback, straight to Piper. */
+  let piperOnly = false;
  if (key) {
    const hit = synthCache.get(key);
    if (hit) {
@@ -941,8 +997,23 @@ async function speak(job) {
             counted as one; the key is deleted below so the NEXT utterance
             tries the natural voice again. */
          if (premiumPick && done.source !== premiumPick.provider) { cloudStats.fallback++; fallbackAt = Date.now(); }
+          /*
+           * ...but only a fallback in THIS language's own Piper voice. The key
+           * names the PREMIUM voice, and spa_Latn, spa_ES and spa_MX share it
+           * (KOKORO_LANG maps all three to 'e', both Portugueses to 'p'). Their
+           * Piper fallbacks they do not share: spa_ES falls back to davefx,
+           * spa_Latn to ald, por_PT to miro, por_Latn to jeff. Cloning the
+           * leader's fallback put the Mexican voice in the Castilian stream for
+           * that sentence — measured in a harness against this file: spa_ES's
+           * clip was the byte-identical ald file and davefx never even loaded.
+           * So the follower still skips the sidecar that just missed (the
+           * variants still switch together), but in its own voice.
+           */
+          if (done.source !== 'piper' || done.bundle === (voice.bundle || '')) {
            return cloneClip(done, job.lang, started);
          }
+          piperOnly = true;
+        }
      } catch (_) { /* the first caller failed — make our own */ }
    }
  }
@@ -956,7 +1027,7 @@ async function speak(job) {
     * alternate skips the premium path entirely — otherwise cloudSynth would
     * fall back to the operator's own pick and the page would lie.
     */
-    const cloudOut = (alt && alt.engine === 'builtin')
+    const cloudOut = (piperOnly || (alt && alt.engine === 'builtin'))
      ? null
      : await cloudSynth(job.lang, text, (alt && alt.engine !== 'builtin') ? alt : null, { speed: kokoroSpeed, deadline });
    if (cloudOut) {
@@ -984,13 +1055,16 @@ async function speak(job) {
        source: cloudOut.provider
      };
    }
-    if (!(alt && alt.engine === 'builtin') && cloudVoiceFor(job.lang)) {
+    /* A piperOnly job's fallback was already counted at the cache hit. */
+    if (!piperOnly && !(alt && alt.engine === 'builtin') && cloudVoiceFor(job.lang)) {
      cloudStats.fallback++;
      fallbackAt = Date.now();
      if (cloudStats.fallback === 1 || cloudStats.fallback % 10 === 0) pushStats('fallback');
    }

-    const tts = await engineFor(job.lang, voice.bundle ? voice : null);
+    /* Live: a sentence is speaking with this voice, so no audition may take
+       its engine. A listener's built-in alternate counts — someone is on it. */
+    const tts = await engineFor(voice.bundle ? voice : null, true, job.lang);
    if (!sherpa) sherpa = require('sherpa-onnx-node');

    /*
@@ -1067,6 +1141,9 @@ async function speak(job) {
    const seconds = secs;
    return {
      source: 'piper',
+      /* WHICH Piper voice spoke it. A follower may share a fallback only when
+         it is its own voice — see the cache hit above. */
+      bundle: voice.bundle || '',
      /* What the sentence ended on — the stream gives a full stop a full breath
         and a mid-thought fragment only a beat. */
      terminal: text.slice(-1),
@@ -1080,8 +1157,12 @@ async function speak(job) {
    };
  };

+  /* A piperOnly job is a fallback by construction. It must not stand in the
+     cache as a leader, or the next identical line would inherit the miss
+     without trying the natural voice — the chorus case below. */
+  const cacheKey = piperOnly ? null : key;
  const promise = produce();
-  if (key) synthCache.set(key, { promise, at: Date.now() });
+  if (cacheKey) synthCache.set(cacheKey, { promise, at: Date.now() });
  try {
    const out = await promise;
    /*
@@ -1091,10 +1172,10 @@ async function speak(job) {
     * miss would have re-created the very voice switch this file exists to
     * prevent (measured in the harness before shipping, not after).
     */
-    if (key && premiumPick && out && out.source !== premiumPick.provider) synthCache.delete(key);
+    if (cacheKey && premiumPick && out && out.source !== premiumPick.provider) synthCache.delete(cacheKey);
    return out;
  } catch (e) {
-    if (key) synthCache.delete(key);
+    if (cacheKey) synthCache.delete(cacheKey);
    throw e;
  }
 }
@@ -1187,11 +1268,15 @@ process.on('message', async (msg) => {
    if (msg.type === 'voices') {
      /* The operator changed a per-language voice choice. */
      voiceChoice = msg.choices || {};
-      /* Drop cached engines for languages whose choice changed, so the next
-         sentence uses the new voice rather than the one already resident. */
-      for (const k of Array.from(loaded.keys())) {
-        if (!String(k).startsWith("audition:")) loaded.delete(k);
-      }
+      /*
+       * Nothing to drop. Engines are keyed by bundle, so a changed choice
+       * resolves to a different engine on the next sentence by itself, and
+       * the one it replaced ages out like any other. The loop that was here
+       * only ever deleted the preload's per-language copies (the live path was
+       * filed under 'audition:'); under bundle keys it would delete the live
+       * engines too, and every "Use it" would make the next sentence rebuild
+       * every language's voice.
+       */
      reply({ type: 'voicesOk', count: Object.keys(voiceChoice).length });
      return;
    }
@@ -1222,7 +1307,9 @@ process.on('message', async (msg) => {
        } finally { voiceChoice = saved; }
      } else {
        if (!sherpa) sherpa = require('sherpa-onnx-node');
-        const tts = await engineFor(msg.lang, spec.bundle ? spec : null);
+        /* Not live: shares the engine when this voice is already speaking,
+           otherwise takes an audition slot — never a live one. */
+        const tts = await engineFor(spec.bundle ? spec : builtinVoiceFor(msg.lang), false, 'audition');
        const audio = tts.generate({ text, sid: spec.sid || 0, speed: spec.speed || 1.0 });
        if (spec.gain && spec.gain !== 1) {
          for (let i = 0; i < audio.samples.length; i++) {
@@ -1256,7 +1343,9 @@ process.on('message', async (msg) => {
      /* Warm the languages people are actually listening to, so the first
         sentence of a service is not the one that pays for the download. */
      for (const lang of msg.langs || []) {
-        try { await engineFor(lang); } catch (e) { log('preload failed for ' + lang + ': ' + e.message); }
+        /* Keyed exactly as speak() keys it, so this warms the engine the first
+           sentence will read, not a copy beside it. */
+        try { await engineFor(builtinVoiceFor(lang), true, lang); } catch (e) { log('preload failed for ' + lang + ': ' + e.message); }
      }
      reply({ type: 'preloaded', langs: msg.langs || [] });
      return;
@@ -0,0 +1,78 @@
+/*
+ * voice-install.js — download and unpack ONE voice bundle, in a worker thread.
+ *
+ * This work used to run on the voice process's own event loop, from inside
+ * engineFor(), the moment a sentence arrived for a language whose voice was
+ * not installed. MEASURED on a campus Mac, 2026-10-15 15:11: a listener tapped
+ * Chinese, three parallel downloads and unpacks of the 121 MB zh model ran at
+ * once on the thread that has to answer every sentence, every other language
+ * stalled for about a minute, 26 sentences were dropped, and the catch-up
+ * pushed the Spanish voices to their +16% rush cap — reported from the pews
+ * as the voice "changing". bzip2 in pure JS is CPU work; it has no business on
+ * that thread.
+ *
+ * So the whole fetch-check-unpack now happens here, off the loop, and
+ * tts-service.js de-duplicates it per bundle. The archive is unpacked into a
+ * staging folder and renamed into place only when complete, so a half-written
+ * bundle can never pass isInstalled() and be handed to sherpa.
+ */
+'use strict';
+const { parentPort, workerData } = require('worker_threads');
+const fs = require('fs');
+const path = require('path');
+
+const { url, voiceDir, bundle } = workerData;
+
+(async () => {
+  fs.mkdirSync(voiceDir, { recursive: true });
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error('HTTP ' + res.status);
+  const body = Buffer.from(await res.arrayBuffer());
+  /* A proxy or a captive portal returns an HTML error page with HTTP 200;
+     the bzip2 magic is the cheapest way to notice before unpacking it. */
+  if (body.length < 1024 || body.toString('latin1', 0, 3) !== 'BZh') {
+    throw new Error('that download was not a voice bundle');
+  }
+  parentPort.postMessage({ status: 'installing' });
+
+  const bunzip = require('unbzip2-stream');
+  const tar = require('tar-stream');
+  const { Readable } = require('stream');
+
+  const staging = path.join(voiceDir, '.installing-' + bundle + '-' + process.pid);
+  fs.rmSync(staging, { recursive: true, force: true });
+  fs.mkdirSync(staging, { recursive: true });
+
+  await new Promise((resolve, reject) => {
+    const extract = tar.extract();
+    extract.on('entry', (header, stream, next) => {
+      /* Never write outside the staging folder, whatever the archive claims. */
+      const dest = path.resolve(staging, header.name);
+      if (dest !== staging && !dest.startsWith(staging + path.sep)) {
+        stream.resume(); return next();
+      }
+      if (header.type === 'directory') {
+        fs.mkdirSync(dest, { recursive: true });
+        stream.resume(); return next();
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      stream.pipe(fs.createWriteStream(dest)).on('finish', next).on('error', reject);
+    });
+    extract.on('finish', resolve);
+    extract.on('error', reject);
+    Readable.from(body).pipe(bunzip()).on('error', reject).pipe(extract);
+  });
+
+  /* The archive's top-level folder is the bundle name — that is what
+     voicePath() opens. Swap it into place in one rename. */
+  const unpacked = path.join(staging, bundle);
+  if (!fs.existsSync(unpacked)) throw new Error('the archive did not contain ' + bundle);
+  const final = path.join(voiceDir, bundle);
+  fs.rmSync(final, { recursive: true, force: true });
+  fs.renameSync(unpacked, final);
+  fs.rmSync(staging, { recursive: true, force: true });
+
+  parentPort.postMessage({ status: 'ready' });
+})().catch((err) => {
+  parentPort.postMessage({ status: 'error', message: (err && err.message) || String(err) });
+});