@chatpanel/gateway 0.6.56 → 0.6.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.56",
+  "version": "0.6.58",
   "description": "Local privacy gateway — redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {

package/src/config.js

@@ -119,8 +119,13 @@ export const DEFAULTS = {
     // client as everywhere else here; no key is stored. See src/tts-remote.js for
     // why remote synthesis redacts by default and what that costs.
     provider: 'local',
-    model: 'onnx-community/Kokoro-82M-v1.0-ONNX',
-    voice: 'af_heart',
+    // Empty = decide at runtime. Pocket TTS is the better default (fastest here,
+    // and the only engine that can speak as you) but needs the native onnxruntime,
+    // which the standalone binary does not carry — so hardcoding either one is
+    // wrong for half the installs. resolveDefaultModel() picks per runtime, and an
+    // explicit choice here always wins.
+    model: '',
+    voice: '',
     allowDownload: true,
     remote: {
       baseUrl: '',   // '' = the provider's own default endpoint

package/src/ort.js

@@ -0,0 +1,52 @@
+// One place to get an onnxruntime, for the engines that drive raw ONNX graphs:
+// parakeet (STT) and pocket-tts (TTS). Transformers.js brings its own; these do
+// not, and they were each resolving it separately.
+//
+// KNOWN LIMITATION — raw ORT does not work inside the standalone binary.
+// The Bun build embeds the ORT runtime as a virtual path (.wasm) and a blob: URL
+// (.mjs), and onnxruntime-web reaches for both with fetch(), which serves neither.
+// Handing it the wasm BYTES, pointing wasmPaths at an extracted directory, and
+// importing the wasm-only bundle were all tried; each moves the failure without
+// removing it. Transformers.js works there because it configures its own bundled
+// copy through its own env.
+//
+// This is NOT new — parakeet has had it since it shipped; it simply failed as an
+// opaque "no available backend found" instead of saying so. Models that need this
+// runtime are now marked `requiresNative` in their catalogs and are not offered on
+// the binary, so the npm gateway is the answer rather than a broken download.
+
+let _promise = null;
+
+/** Is a raw-ONNX engine usable in this process? False inside the binary. */
+export function rawOrtAvailable() {
+  return !globalThis.__CHATPANEL_WASM_PATHS__;
+}
+
+export function ortRuntimeName() {
+  return globalThis.__CHATPANEL_WASM_PATHS__ ? 'wasm' : 'native';
+}
+
+// 'wasm' in the binary, 'cpu' on the native build. The wrong one makes ORT fall
+// through its provider list and report a confusing "no available backend".
+export function ortProviders() {
+  return globalThis.__CHATPANEL_WASM_PATHS__ ? ['wasm'] : ['cpu'];
+}
+
+export function getOrt() {
+  if (_promise) return _promise;
+  _promise = (async () => {
+    const wasmPaths = globalThis.__CHATPANEL_WASM_PATHS__ || null;
+    if (!wasmPaths) {
+      const mod = await import('onnxruntime-node');
+      return mod.InferenceSession ? mod : (mod.default || mod);
+    }
+
+    // Say what is actually wrong. ORT's own message describes a failed fetch and
+    // sends people looking for a corrupt download.
+    throw new Error(
+      'this model needs the native onnxruntime, which the standalone binary does not carry — '
+      + 'install the npm gateway instead (npm i -g @chatpanel/gateway), or pick a model that runs on the bundled runtime',
+    );
+  })();
+  return _promise;
+}

package/src/parakeet-engine.js

@@ -26,6 +26,7 @@ import { join } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, createWriteStream, renameSync, statSync } from 'node:fs';
 import { Readable } from 'node:stream';
 import { modelRoot } from './ner-engine.js';
+import { getOrt, ortProviders } from './ort.js';
 
 // transformers.js reports these `model_type`s for the transducer exports. Any of them
 // means "not a whisper pipeline model — route here instead".
@@ -72,20 +73,6 @@ export function parakeetOnDisk(modelId, dtype = PARAKEET_DEFAULT_DTYPE) {
 // The npm gateway uses native onnxruntime-node (fast). The standalone binary embeds the
 // onnxruntime-web WASM runtime and hands us its paths via __CHATPANEL_WASM_PATHS__ (the
 // same global ner-engine keys off) — configure ORT-web from it. Memoized once.
-let _ortPromise = null;
-function getOrt() {
-  if (_ortPromise) return _ortPromise;
-  _ortPromise = (async () => {
-    const wasmPaths = globalThis.__CHATPANEL_WASM_PATHS__ || null;
-    const mod = await import(wasmPaths ? 'onnxruntime-web' : 'onnxruntime-node');
-    const ort = mod.InferenceSession ? mod : (mod.default || mod);
-    if (wasmPaths) {
-      try { ort.env.wasm.numThreads = 1; ort.env.wasm.proxy = false; ort.env.wasm.wasmPaths = wasmPaths; } catch { /* optional */ }
-    }
-    return ort;
-  })();
-  return _ortPromise;
-}
 
 // ── download (only when a model isn't already on disk) ───────────────────────────────
 // Custom/BYO STT ids aren't on the dl.chatpanel.net mirror, so — like stt-engine's
@@ -166,7 +153,7 @@ export async function loadRecognizer({ modelId, dtype = PARAKEET_DEFAULT_DTYPE,
 
   const ort = await getOrt();
   const s = dt === 'fp32' ? '' : '.int8';
-  const opts = { executionProviders: ['cpu'], graphOptimizationLevel: 'all', logSeverityLevel: 3 };
+  const opts = { executionProviders: ortProviders(), graphOptimizationLevel: 'all', logSeverityLevel: 3 };
   const [prep, encoder, decoder] = await Promise.all([
     ort.InferenceSession.create(join(dir, 'nemo128.onnx'), opts),
     ort.InferenceSession.create(join(dir, `encoder-model${s}.onnx`), opts),

package/src/pocket-tts-engine.js

@@ -27,8 +27,12 @@ import { existsSync, mkdirSync, readFileSync, statSync, createWriteStream, renam
 import { Readable } from 'node:stream';
 import { modelRoot } from './ner-engine.js';
 import { SentencePieceUnigram } from './sentencepiece.js';
+import { getOrt, ortProviders } from './ort.js';
 
 export const POCKET_REPO = 'KevinAHM/pocket-tts-onnx';
+// The built-in speakers live in the demo Space, not the weights repo — the weights
+// repo 404s on voices.bin. Same author, same licence, different HF namespace.
+export const POCKET_VOICES_SPACE = 'KevinAHM/pocket-tts-web';
 export const DEFAULT_BUNDLE = 'english_2026-04';
 export const SAMPLE_RATE = 24000;
 
@@ -43,30 +47,16 @@ const NORMAL_CHUNK_FRAMES = 12;
 // sentence's trailing state colour the next one's opening.
 const RESET_STATE_EACH_CHUNK = true;
 
-// voices.bin (the reference implementation's PREDEFINED speakers) is deliberately
-// absent: it lives only in the demo Space, not the weights repo, and this engine
-// exists to speak in a voice the user recorded. Kokoro already covers "pick a
-// stock voice", and far better.
 const FILES = (q = '_int8') => [
   'bundle.json', 'tokenizer.model', 'bos_before_voice.npy',
   `text_conditioner${q}.onnx`, `mimi_encoder${q}.onnx`, `mimi_decoder${q}.onnx`,
   `flow_lm_main${q}.onnx`, `flow_lm_flow${q}.onnx`,
 ];
+// voices.bin is a separate ~52 MB download for the eight built-in speakers, and it
+// is OPTIONAL: cloning works without it, so a failed or skipped fetch costs the
+// stock voices and nothing else.
+const VOICES_FILE = 'voices.bin';
 
-let _ortPromise = null;
-function getOrt() {
-  if (_ortPromise) return _ortPromise;
-  _ortPromise = (async () => {
-    const wasmPaths = globalThis.__CHATPANEL_WASM_PATHS__ || null;
-    const mod = await import(wasmPaths ? 'onnxruntime-web' : 'onnxruntime-node');
-    const ort = mod.InferenceSession ? mod : (mod.default || mod);
-    if (wasmPaths) {
-      try { ort.env.wasm.numThreads = 1; ort.env.wasm.proxy = false; ort.env.wasm.wasmPaths = wasmPaths; } catch { /* optional */ }
-    }
-    return ort;
-  })();
-  return _ortPromise;
-}
 
 export function bundleDir(bundle = DEFAULT_BUNDLE) {
   return join(modelRoot(), 'pocket-tts', bundle);
@@ -80,7 +70,9 @@ export function bundleOnDisk(bundle = DEFAULT_BUNDLE, quant = '_int8') {
 }
 
 async function downloadFile(bundle, file, dir, { onProgress, log } = {}) {
-  const url = `https://huggingface.co/${POCKET_REPO}/resolve/main/onnx/${bundle}/${file}`;
+  const url = file === VOICES_FILE
+    ? `https://huggingface.co/spaces/${POCKET_VOICES_SPACE}/resolve/main/onnx/${bundle}/${file}`
+    : `https://huggingface.co/${POCKET_REPO}/resolve/main/onnx/${bundle}/${file}`;
   const res = await fetch(url, { redirect: 'follow' });
   if (!res.ok || !res.body) throw new Error(`fetch ${file} → HTTP ${res.status}`);
   const total = Number(res.headers.get('content-length')) || 0;
@@ -110,6 +102,21 @@ export async function ensureBundle(bundle = DEFAULT_BUNDLE, quant = '_int8', { o
   return dir;
 }
 
+/** Fetch the built-in speakers. Optional — failure leaves cloning fully working. */
+export async function ensureVoicesBin(bundle = DEFAULT_BUNDLE, { onProgress, log } = {}) {
+  const dir = bundleDir(bundle);
+  const dest = join(dir, VOICES_FILE);
+  if (existsSync(dest) && statSync(dest).size > 1024) return dest;
+  mkdirSync(dir, { recursive: true });
+  log?.(`[pocket-tts] downloading ${VOICES_FILE} (built-in voices, ~52 MB)…`);
+  await downloadFile(bundle, VOICES_FILE, dir, { onProgress, log });
+  return dest;
+}
+
+export function voicesBinOnDisk(bundle = DEFAULT_BUNDLE) {
+  try { const p = join(bundleDir(bundle), VOICES_FILE); return existsSync(p) && statSync(p).size > 1024; } catch { return false; }
+}
+
 // ── .npy (float32) ──────────────────────────────────────────────────────────────
 export function parseNpyFloat32(buf) {
   const magic = [0x93, 0x4e, 0x55, 0x4d, 0x50, 0x59];
@@ -152,6 +159,102 @@ function advanceState(state, result, manifest) {
   for (const e of manifest) state[e.input_name] = result[e.output_name];
 }
 
+
+// ── built-in speakers ───────────────────────────────────────────────────────────
+// voices.bin (PTVB1) is a flat table of per-voice tensor STATES — the model's
+// internal state after it has been conditioned on that speaker — rather than
+// audio or embeddings. Loading one is therefore not "encode a voice" but "restore
+// the state a voice produces", which is why it takes a different path from cloning.
+export function parseVoicesBin(buf) {
+  const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  const view = new DataView(ab);
+  let off = 0;
+  const magic = new TextDecoder().decode(new Uint8Array(ab, 0, 5));
+  off += 5;
+  if (magic !== 'PTVB1') throw new Error('not a voices.bin (bad header)');
+  const voices = {};
+  const count = view.getUint32(off, true); off += 4;
+  for (let v = 0; v < count; v++) {
+    const nameLen = view.getUint16(off, true); off += 2;
+    const name = new TextDecoder().decode(new Uint8Array(ab, off, nameLen)); off += nameLen;
+    const tensorCount = view.getUint16(off, true); off += 2;
+    const tensors = {};
+    for (let t = 0; t < tensorCount; t++) {
+      const keyLen = view.getUint16(off, true); off += 2;
+      const key = new TextDecoder().decode(new Uint8Array(ab, off, keyLen)); off += keyLen;
+      const dtypeCode = view.getUint8(off); off += 1;
+      const rank = view.getUint8(off); off += 1;
+      const shape = [];
+      for (let d = 0; d < rank; d++) { shape.push(view.getUint32(off, true)); off += 4; }
+      const byteLength = view.getUint32(off, true); off += 4;
+      const slice = ab.slice(off, off + byteLength);
+      const data = dtypeCode === 0 ? new Float32Array(slice)
+        : dtypeCode === 1 ? new BigInt64Array(slice)
+          : dtypeCode === 2 ? new Uint8Array(slice)
+            : (() => { throw new Error(`unsupported voices.bin dtype ${dtypeCode}`); })();
+      off += byteLength;
+      tensors[key] = { data, shape, dtype: dtypeCode === 0 ? 'float32' : dtypeCode === 1 ? 'int64' : 'bool' };
+    }
+    voices[name] = tensors;
+  }
+  return voices;
+}
+
+// A saved state is keyed "module/tensor"; the manifest addresses the same tensors
+// by module + key, so the flat table is regrouped before it can be matched.
+function groupByModule(record) {
+  const grouped = {};
+  for (const [k, v] of Object.entries(record)) {
+    const i = k.indexOf('/');
+    if (i === -1) continue;
+    (grouped[k.slice(0, i)] ||= {})[k.slice(i + 1)] = v;
+  }
+  return grouped;
+}
+
+// Some modules record their position under a different name (or not at all), so
+// the manifest's `step` is derived from whichever the module actually kept.
+function deriveStep(moduleState) {
+  if (moduleState.step) return { data: BigInt64Array.from([BigInt(moduleState.step.data[0])]), shape: [1], dtype: 'int64' };
+  if (moduleState.offset && !moduleState.end_offset) return { data: BigInt64Array.from([BigInt(moduleState.offset.data[0])]), shape: [1], dtype: 'int64' };
+  if (moduleState.current_end) return { data: BigInt64Array.from([BigInt(moduleState.current_end.shape[0])]), shape: [1], dtype: 'int64' };
+  return { data: BigInt64Array.from([0n]), shape: [1], dtype: 'int64' };
+}
+
+// A saved tensor may not match the manifest's shape exactly (a shorter cache, say).
+// Copy what overlaps into a correctly-shaped, correctly-filled target rather than
+// handing ORT a tensor of the wrong rank.
+function adaptTensor(source, entry) {
+  const target = filledArray(entry.shape, entry.dtype, entry.fill);
+  const targetSize = entry.shape.reduce((a, b) => a * b, 1);
+  const Ctor = entry.dtype === 'int64' ? BigInt64Array : entry.dtype === 'bool' ? Uint8Array : Float32Array;
+  const sameRank = source.shape.length === entry.shape.length;
+  if ((sameRank && source.shape.every((d, i) => d === entry.shape[i])) || source.data.length === targetSize) {
+    return new Ctor(source.data);
+  }
+  if (!sameRank) return target;
+  const strides = [];
+  let stride = 1;
+  for (let i = source.shape.length - 1; i >= 0; i--) { strides[i] = stride; stride *= source.shape[i]; }
+  const idx = new Array(source.shape.length).fill(0);
+  const max = source.shape.map((d, i) => Math.min(d, entry.shape[i]));
+  if (max.some((m) => m === 0)) return target;
+  for (;;) {
+    let si = 0;
+    for (let i = 0; i < idx.length; i++) si += idx[i] * strides[i];
+    let ti = 0, ts = 1;
+    for (let i = entry.shape.length - 1; i >= 0; i--) { ti += idx[i] * ts; ts *= entry.shape[i]; }
+    target[ti] = source.data[si];
+    let dim = idx.length - 1;
+    for (; dim >= 0; dim--) {
+      if (++idx[dim] < max[dim]) break;
+      idx[dim] = 0;
+      if (dim === 0) return target;
+    }
+    if (dim < 0) return target;
+  }
+}
+
 export class PocketTTS {
   constructor() {
     this.ready = false;
@@ -164,8 +267,12 @@ export class PocketTTS {
     this.latentDim = 32;
     this.condDim = 1024;
     this.samplesPerFrame = 1920;
+    this.builtin = null;        // name → saved tensor state, from voices.bin
   }
 
+  /** The built-in speaker names available, or [] if voices.bin was not fetched. */
+  builtinVoices() { return this.builtin ? Object.keys(this.builtin).sort() : []; }
+
   async load(bundle = DEFAULT_BUNDLE, { quant = '_int8', onProgress, log = () => {} } = {}) {
     const dir = await ensureBundle(bundle, quant, { onProgress, log });
     const ort = await getOrt();
@@ -176,7 +283,7 @@ export class PocketTTS {
     this.condDim = Number(this.meta.conditioning_dim) || 1024;
     this.samplesPerFrame = Math.round(SAMPLE_RATE / (Number(this.meta.frame_rate) || 12.5));
 
-    const opts = { executionProviders: ['cpu'], graphOptimizationLevel: 'all', logSeverityLevel: 3 };
+    const opts = { executionProviders: ortProviders(), graphOptimizationLevel: 'all', logSeverityLevel: 3 };
     const [textConditioner, mimiEncoder, mimiDecoder, flowMain, flowFlow] = await Promise.all([
       ort.InferenceSession.create(join(dir, `text_conditioner${quant}.onnx`), opts),
       ort.InferenceSession.create(join(dir, `mimi_encoder${quant}.onnx`), opts),
@@ -197,6 +304,12 @@ export class PocketTTS {
         t: new ort.Tensor('float32', new Float32Array([s + dt]), [1, 1]),
       });
     }
+    // Built-in speakers are optional: a missing or unreadable voices.bin costs the
+    // stock voices and leaves cloning — the reason this engine exists — untouched.
+    try {
+      if (voicesBinOnDisk(bundle)) this.builtin = parseVoicesBin(readFileSync(join(dir, 'voices.bin')));
+    } catch (e) { log(`[pocket-tts] built-in voices unavailable (${e.message})`); }
+
     this.bundle = bundle;
     this.ready = true;
     log(`[pocket-tts] ready — ${bundle} (${quant.replace('_', '') || 'fp32'}, ${SAMPLE_RATE} Hz)`);
@@ -236,6 +349,22 @@ export class PocketTTS {
     return new ort.Tensor('float32', data, dims);
   }
 
+  // Restore the flow-LM state a built-in speaker was saved with.
+  #builtinState(name) {
+    const record = this.builtin?.[name];
+    if (!record) throw new Error(`unknown built-in voice: ${name}`);
+    const { ort } = this.sessions;
+    const grouped = groupByModule(record);
+    const state = initState(ort, this.meta.flow_lm_state_manifest);
+    for (const e of this.meta.flow_lm_state_manifest) {
+      const moduleState = grouped[e.module] || {};
+      const source = moduleState[e.key] || (e.key === 'step' ? deriveStep(moduleState) : null);
+      if (!source) continue;
+      state[e.input_name] = new ort.Tensor(e.dtype, adaptTensor(source, e), e.shape);
+    }
+    return state;
+  }
+
   async #voiceState(voice) {
     const { ort, flowMain } = this.sessions;
     const state = initState(ort, this.meta.flow_lm_state_manifest);
@@ -288,12 +417,17 @@ export class PocketTTS {
    */
   async synth(text, { voice, onAudio = null } = {}) {
     if (!this.ready) throw new Error('pocket-tts not loaded');
-    if (!voice?.data?.length) throw new Error('pocket-tts needs a voice — record one');
+    // Either a cloned voice ({data, shape} from encodeVoice) or a built-in name.
+    if (typeof voice === 'string') {
+      if (!this.builtin?.[voice]) throw new Error(`unknown built-in voice: ${voice}`);
+    } else if (!voice?.data?.length) {
+      throw new Error('pocket-tts needs a voice — record one, or pick a built-in');
+    }
     const { ort, textConditioner, flowMain, flowFlow, mimiDecoder } = this.sessions;
     const prepared = this.#prepare(text);
     if (!prepared.text) return new Float32Array(0);
     const chunks = this.#chunks(prepared.text);
-    const baseFlow = await this.#voiceState(voice);
+    const baseFlow = typeof voice === 'string' ? this.#builtinState(voice) : await this.#voiceState(voice);
 
     const emptySeq = new ort.Tensor('float32', new Float32Array(0), [1, 0, this.latentDim]);
     const emptyText = new ort.Tensor('float32', new Float32Array(0), [1, 0, this.condDim]);

package/src/server.js

@@ -40,8 +40,9 @@ import * as diarizeEngine from './diarize-engine.js';
 import { MODEL_CATALOG, isKnownModel, isValidCustomModelId } from './models.js';
 import { STT_MODEL_CATALOG, isKnownSttModel, isValidCustomSttId, DEFAULT_STT_MODEL, STT_DTYPES, isValidDtype } from './stt-models.js';
 import * as ttsEngine from './tts-engine.js';
-import { TTS_MODEL_CATALOG, TTS_VOICES, isKnownTtsModel, isValidCustomTtsId, isKnownVoice, isValidVoiceId, DEFAULT_TTS_MODEL, DEFAULT_TTS_VOICE, TTS_DTYPES, isValidTtsDtype, MAX_TTS_CHARS, ttsModelHasCustomVoices } from './tts-models.js';
+import { TTS_MODEL_CATALOG, TTS_VOICES, isKnownTtsModel, isValidCustomTtsId, isKnownVoice, isValidVoiceId, DEFAULT_TTS_MODEL, DEFAULT_TTS_VOICE, TTS_DTYPES, isValidTtsDtype, MAX_TTS_CHARS, ttsModelHasCustomVoices, ttsModelRequiresNative, resolveDefaultModel, POCKET_VOICES, DEFAULT_POCKET_VOICE, isPocketVoice, ttsModelEngine as ttsModelEngineOf } from './tts-models.js';
 import { ttsDestination, synthesizeRemote, isValidRemoteVoice } from './tts-remote.js';
+import { rawOrtAvailable } from './ort.js';
 import * as ttsVoices from './tts-voices.js';
 import { resolvePro, checkQuota, consume, usage } from './freegate.js';
 import { publicConfig, applyConfigPatch, applyNerModelSelection, persistConfig, configPath } from './configstore.js';
@@ -53,7 +54,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.56';
+export const VERSION = '0.6.58';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -998,8 +999,17 @@ export function createGateway(cfg = loadConfig()) {
     // docs/voice-pipeline.md. Model manager first, then synthesis.
     if (pathname === '/tts/models') {
       if (req.method === 'GET') {
-        const active = ttsEngine.health().model || cfg.tts?.model || DEFAULT_TTS_MODEL;
-        const available = /** @type {any[]} */ (TTS_MODEL_CATALOG.map((m) => ({ ...m, installed: ttsEngine.modelOnDisk(m.id) })));
+        const active = ttsEngine.health().model || cfg.tts?.model || resolveDefaultModel(rawOrtAvailable());
+        // A model needing the native runtime is still LISTED on the binary, with the
+        // reason — hiding it makes "why can't I clone my voice?" unanswerable.
+        const nativeOk = rawOrtAvailable();
+        const available = /** @type {any[]} */ (TTS_MODEL_CATALOG.map((m) => ({
+          ...m,
+          installed: ttsEngine.modelOnDisk(m.id),
+          unavailable: m.requiresNative && !nativeOk
+            ? 'needs the npm gateway — the standalone binary cannot load this engine'
+            : undefined,
+        })));
         if (active && !available.some((m) => m.id === active)) {
           available.push({ id: active, label: active, lang: '—', tier: 'custom', custom: true, installed: ttsEngine.modelOnDisk(active), note: 'Custom model (from Hugging Face).' });
         }
@@ -1008,7 +1018,9 @@ export function createGateway(cfg = loadConfig()) {
           state: ttsEngine.state(),
           progress: ttsEngine.progress(),
           available,
-          voice: cfg.tts?.voice || DEFAULT_TTS_VOICE,
+          // The default voice belongs to the model's own namespace: Kokoro's
+          // af_heart means nothing to Pocket, and vice versa.
+          voice: cfg.tts?.voice || (ttsModelEngineOf(active) === 'pocket-tts' ? DEFAULT_POCKET_VOICE : DEFAULT_TTS_VOICE),
           // Architecture decides whether voices mean anything: Kokoro picks one from
           // a style bank, VITS/MMS is single-speaker. An empty list tells the UI to
           // hide the picker rather than offer choices that cannot take effect.
@@ -1019,9 +1031,14 @@ export function createGateway(cfg = loadConfig()) {
           // Built-in voices belong to Kokoro alone. VITS is single-speaker and
           // SpeechT5 speaks only in a RECORDED voice, so offering Kokoro's list
           // for either would be offering choices that cannot take effect.
-          voices: ttsEngine.arch() && ttsEngine.arch() !== 'style-tts2'
-            ? []
-            : TTS_VOICES.map((v) => ({ ...v, installed: ttsEngine.voiceOnDisk(v.id, active) })),
+          voices: (ttsEngine.isPocket() || (!ttsEngine.arch() && ttsModelEngineOf(active) === 'pocket-tts'))
+            // Pocket ships eight speakers in an optional 52 MB file; report what is
+            // actually loaded rather than the catalog's aspiration.
+            ? (ttsEngine.builtinVoices().length ? ttsEngine.builtinVoices() : POCKET_VOICES)
+              .map((n) => ({ id: n, label: n[0].toUpperCase() + n.slice(1), lang: 'en', installed: ttsEngine.builtinVoices().includes(n) }))
+            : ttsEngine.arch() && ttsEngine.arch() !== 'style-tts2'
+              ? []
+              : TTS_VOICES.map((v) => ({ ...v, installed: ttsEngine.voiceOnDisk(v.id, active) })),
           dtype: cfg.tts?.dtype || 'auto',
           loadedDtype: ttsEngine.health().dtype,
           runtime: ttsEngine.health().runtime,
@@ -1040,7 +1057,7 @@ export function createGateway(cfg = loadConfig()) {
         const voice = body && typeof body.voice === 'string' ? body.voice.trim() : null;
         if (voice) {
           const cid = ttsVoices.parseCustomVoice(voice);
-          const okVoice = cid ? !!ttsVoices.getVoice(cid) : (isKnownVoice(voice) && isValidVoiceId(voice));
+          const okVoice = cid ? !!ttsVoices.getVoice(cid) : (isPocketVoice(voice) || (isKnownVoice(voice) && isValidVoiceId(voice)));
           if (!okVoice) return sendJson(res, 400, { error: { message: 'unknown or invalid voice', type: 'bad_voice' } });
         }
         const dtype = body && typeof body.dtype === 'string' && isValidTtsDtype(body.dtype) ? body.dtype : undefined;
@@ -1066,6 +1083,11 @@ export function createGateway(cfg = loadConfig()) {
           } else if (!wantsCustom && isCustom) {
             cfg.tts.voice = DEFAULT_TTS_VOICE;
           }
+          // Kokoro and Pocket name their speakers differently; carrying one over
+          // leaves a voice the new model has never heard of.
+          const toPocket = ttsModelEngineOf(id) === 'pocket-tts';
+          if (toPocket && !ttsVoices.parseCustomVoice(cfg.tts.voice || '') && !isPocketVoice(cfg.tts.voice)) cfg.tts.voice = DEFAULT_POCKET_VOICE;
+          if (!toPocket && isPocketVoice(cfg.tts.voice)) cfg.tts.voice = DEFAULT_TTS_VOICE;
         }
         if (dtype) cfg.tts.dtype = dtype === 'auto' ? null : dtype;
         try { persistConfig(cfg, configPath()); } catch { /* best effort */ }
@@ -1095,7 +1117,26 @@ export function createGateway(cfg = loadConfig()) {
         try { body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')); } catch { body = null; }
         const name = body && typeof body.name === 'string' ? body.name.trim() : '';
         const pcm = body && Array.isArray(body.pcm) ? body.pcm : null;
-        if (!name) return sendJson(res, 400, { error: { message: 'a name is required', type: 'bad_request' } });
+        // An `id` means UPDATE an existing voice rather than create one. The id is
+        // preserved either way, because `custom:<id>` is what the config and every
+        // client hold — a rename or a re-record must not orphan those.
+        const editId = body && typeof body.id === 'string' ? body.id.trim() : '';
+        if (editId) {
+          if (!ttsVoices.getVoice(editId)) return sendJson(res, 404, { error: { message: 'no such saved voice', type: 'bad_voice' } });
+          // Rename only — no new audio, so the prints are left exactly as they are.
+          if (!pcm) {
+            if (!name) return sendJson(res, 400, { error: { message: 'a name is required', type: 'bad_request' } });
+            try {
+              return sendJson(res, 200, { ...ttsVoices.renameVoice(editId, name), usable: ttsEngine.supportsCustomVoices() });
+            } catch (e) { return sendJson(res, 400, { error: { message: e.message, type: 'rename_failed' } }); }
+          }
+          // Re-record: same rules as a fresh take, then swap the prints in place.
+          if (pcm.length < 16000) {
+            return sendJson(res, 400, { error: { message: 'need at least 1 second of 16 kHz mono audio', type: 'sample_too_short' } });
+          }
+        } else if (!name) {
+          return sendJson(res, 400, { error: { message: 'a name is required', type: 'bad_request' } });
+        }
         if (!pcm || pcm.length < 16000) {
           // Under a second of audio produces an embedding dominated by whatever
           // noise happened to be in it, and the resulting voice is arbitrary.
@@ -1144,9 +1185,13 @@ export function createGateway(cfg = loadConfig()) {
             console.log(`[tts] pocket conditioning unavailable for this voice (${e.message})`);
           }
 
-          const saved = ttsVoices.saveVoice({ name, vec, pocket });
-          console.log(`[tts] saved custom voice "${saved.name}" (${saved.kinds.join(' + ')}, sample discarded)`);
-          return sendJson(res, 201, { ...saved, usable: ttsEngine.supportsCustomVoices() });
+          const saved = editId
+            ? ttsVoices.replaceVoice(editId, { vec, pocket })
+            : ttsVoices.saveVoice({ name, vec, pocket });
+          // A rename may ride along with a re-record, so apply it after the swap.
+          const final = editId && name && name !== saved.name ? ttsVoices.renameVoice(editId, name) : saved;
+          console.log(`[tts] ${editId ? 're-recorded' : 'saved'} custom voice "${final.name}" (${(saved.kinds || []).join(' + ')}, sample discarded)`);
+          return sendJson(res, editId ? 200 : 201, { ...saved, ...final, usable: ttsEngine.supportsCustomVoices() });
         } catch (e) {
           return sendJson(res, 400, { error: { message: e.message, type: 'save_failed' } });
         }
@@ -1226,7 +1271,7 @@ export function createGateway(cfg = loadConfig()) {
         const ok = await ttsEngine.ready({
           onLog: (m) => console.log(m),
           allowDownload: cfg.tts?.allowDownload !== false,
-          model: cfg.tts?.model || DEFAULT_TTS_MODEL,
+          model: cfg.tts?.model || resolveDefaultModel(rawOrtAvailable()),
           dtype: cfg.tts?.dtype || 'auto',
         });
         if (!ok) return sendJson(res, 503, { error: { message: ttsEngine.health().error || 'tts model not ready', type: 'tts_unavailable' } });
@@ -1239,7 +1284,13 @@ export function createGateway(cfg = loadConfig()) {
         let speakerEmbedding = null;
         let customId = ttsVoices.parseCustomVoice(voice);
 
-        if (ttsEngine.supportsCustomVoices()) {
+        // A Pocket built-in speaker is a NAME, not an embedding, so it has to be
+        // recognised before the custom-voice path — which would otherwise demand a
+        // recording for a model that ships eight voices of its own.
+        if (ttsEngine.isPocket() && isPocketVoice(rawVoice || useVoice)) {
+          useVoice = rawVoice || useVoice;
+          customId = null;
+        } else if (ttsEngine.supportsCustomVoices()) {
           // This model speaks ONLY in a recorded voice. If the configured one names
           // a built-in (switching model does not rewrite `voice`) or points at a
           // voice since deleted, fall back to the most recent saved one — the
@@ -1249,8 +1300,13 @@ export function createGateway(cfg = loadConfig()) {
           if (!rec && !rawVoice) {
             const saved = ttsVoices.listVoices();
             if (saved.length) { customId = saved[0].id; rec = ttsVoices.getVoice(customId); }
+            // Pocket can fall back to a built-in speaker; SpeechT5 has none, so for
+            // that one "no saved voice" really is the end of the road.
+            else if (ttsEngine.isPocket()) { useVoice = DEFAULT_POCKET_VOICE; customId = null; }
           }
-          if (!rec) {
+          if (!rec && !customId && ttsEngine.isPocket()) {
+            // resolved to a built-in above — nothing more to look up
+          } else if (!rec) {
             return sendJson(res, customId ? 404 : 400, {
               error: {
                 message: customId ? 'no such saved voice' : 'this model speaks in a voice you record — add one in Settings → Text-to-speech',
@@ -1287,7 +1343,11 @@ export function createGateway(cfg = loadConfig()) {
           }
           customId = null;
           useVoice = DEFAULT_TTS_VOICE;
-        } else if (ttsEngine.supportsVoices() && !(isKnownVoice(useVoice) && isValidVoiceId(useVoice))) {
+        } else if (ttsEngine.isPocket() && !isPocketVoice(useVoice)) {
+          // Pocket has its own speaker namespace; a Kokoro voice name here means the
+          // config was carried over from another model, so fall back to its default.
+          useVoice = DEFAULT_POCKET_VOICE;
+        } else if (ttsEngine.supportsVoices() && !ttsEngine.isPocket() && !(isKnownVoice(useVoice) && isValidVoiceId(useVoice))) {
           return sendJson(res, 400, { error: { message: 'unknown or invalid voice', type: 'bad_voice' } });
         }
 

package/src/tts-engine.js

@@ -69,6 +69,8 @@ export const SPEECHT5_VOCODER = 'Xenova/speecht5_hifigan';
 // tried it, but it borrows a voice rather than reproducing one.
 export function supportsCustomVoices() { return _arch === 'speecht5' || _arch === POCKET_ARCH; }
 export function isPocket() { return _arch === POCKET_ARCH; }
+/** The built-in speaker names the loaded Pocket model offers, if any. */
+export function builtinVoices() { return _pocket?.builtinVoices?.() || []; }
 
 /**
  * A PocketTTS instance purely for ENCODING a voice, without disturbing whatever
@@ -359,10 +361,10 @@ export async function synthChunk(text, { voice = DEFAULT_TTS_VOICE, speed = 1, s
   // Pocket TTS runs its own generation loop and chunking, so a whole utterance is
   // handed over at once rather than being pre-split here.
   if (_arch === POCKET_ARCH) {
-    if (!speakerEmbedding?.data?.length) {
-      throw new Error('this model needs a saved voice — record one in Settings → Text-to-speech');
-    }
-    return _pocket.synth(String(text), { voice: speakerEmbedding });
+    // Either a cloned voice (an embedding) or one of its built-in speakers (a name).
+    const v = speakerEmbedding?.data?.length ? speakerEmbedding : voice;
+    if (!v) throw new Error('this model needs a voice — pick a built-in one or record your own');
+    return _pocket.synth(String(text), { voice: v });
   }
 
   // SpeechT5: conditioned by a 512-d speaker embedding, which is the whole point —

package/src/tts-models.js

@@ -16,9 +16,30 @@
 // driveable by a transformers.js class (Kokoro = StyleTextToSpeech2Model). Verify
 // it loads on BOTH runtimes (native q8 + WASM fp32) before listing it.
 
-export const DEFAULT_TTS_MODEL = 'onnx-community/Kokoro-82M-v1.0-ONNX';
+// Pocket TTS is the default where it can run: it is the fastest engine here
+// (7-9x realtime against Kokoro's 2.1x) and the only one that can speak as the
+// user. It needs the native onnxruntime, though, which the standalone binary does
+// not carry — so the binary falls back to Kokoro rather than offering a model it
+// cannot load. See src/ort.js for why.
+export const DEFAULT_TTS_MODEL_NATIVE = 'kyutai/pocket-tts';
+export const DEFAULT_TTS_MODEL_WASM = 'onnx-community/Kokoro-82M-v1.0-ONNX';
+export const DEFAULT_TTS_MODEL = DEFAULT_TTS_MODEL_WASM; // safe default; resolveDefaultModel() picks properly
 export const DEFAULT_TTS_VOICE = 'af_heart';
 
+// The eight speakers shipped in voices.bin. Names only — the data is a ~52 MB
+// optional download, and cloning works without it.
+export const POCKET_VOICES = ['alba', 'azelma', 'cosette', 'eponine', 'fantine', 'javert', 'jean', 'marius'];
+export const DEFAULT_POCKET_VOICE = 'alba';
+
+export function isPocketVoice(v) {
+  return POCKET_VOICES.includes(String(v || ''));
+}
+
+/** The model to use when nothing is configured, given what this runtime can load. */
+export function resolveDefaultModel(rawOrtAvailable = true) {
+  return rawOrtAvailable ? DEFAULT_TTS_MODEL_NATIVE : DEFAULT_TTS_MODEL_WASM;
+}
+
 // Style-vector width in a voices/*.bin file, and the max token window a single
 // forward pass accepts. Both are properties of the Kokoro export, and the engine
 // needs them to slice the voice and to chunk long text.
@@ -70,10 +91,12 @@ export const TTS_MODEL_CATALOG = [
     approxMB: 146,
     ramMB: 700,
     sampleRate: 24000,
-    voices: false,
-    customVoices: true,
+    voices: true,           // eight built-in speakers (optional 52 MB voices.bin)
+    customVoices: true,     // …and it can speak as YOU
     recommended: true,
-    note: 'Kyutai Pocket TTS (MIT code, CC-BY-4.0 weights). Records a few seconds and speaks as you. Needs a saved voice; 146 MB one-time download.',
+    // Raw onnxruntime, which the standalone binary cannot provide.
+    requiresNative: true,
+    note: 'Kyutai Pocket TTS (MIT code, CC-BY-4.0 weights). Eight built-in voices, and it can clone yours. Fastest model here. 146 MB, plus 52 MB if you want the built-in voices. Needs the npm gateway.',
   },
   {
     id: 'Xenova/speecht5_tts',
@@ -175,6 +198,11 @@ export function ttsModelHasCustomVoices(id) {
   return ttsModel(id)?.customVoices === true;
 }
 
+/** Does this model need the native onnxruntime (i.e. not usable in the binary)? */
+export function ttsModelRequiresNative(id) {
+  return ttsModel(id)?.requiresNative === true;
+}
+
 export function ttsModel(id) {
   return TTS_MODEL_CATALOG.find((m) => m.id === id) || null;
 }

package/src/tts-voices.js

@@ -75,7 +75,7 @@ export function listVoices() {
       // in a settings page's JSON.
       if (v?.id && v?.name) {
         out.push({
-          id: v.id, name: v.name, createdAt: v.createdAt || 0, dim: v.vec?.length || 0,
+          id: v.id, name: v.name, createdAt: v.createdAt || 0, updatedAt: v.updatedAt || 0, dim: v.vec?.length || 0,
           kinds: v.pocketShape ? [KIND_SPEECHT5, KIND_POCKET] : [KIND_SPEECHT5],
         });
       }
@@ -133,6 +133,53 @@ export function saveVoice({ name, vec, pocket = null }) {
   return { id: rec.id, name: rec.name, createdAt: rec.createdAt, dim: rec.vec.length, kinds: rec.pocketShape ? [KIND_SPEECHT5, KIND_POCKET] : [KIND_SPEECHT5] };
 }
 
+/**
+ * Rename in place. The id is untouched on purpose: `custom:<id>` is what the
+ * gateway config and every client store, so a rename must not invalidate them.
+ */
+export function renameVoice(id, name) {
+  const rec = getVoice(id);
+  if (!rec) return null;
+  const clean = String(name || '').trim().slice(0, MAX_NAME);
+  if (!clean) throw new Error('a name is required');
+  rec.name = clean;
+  rec.updatedAt = Date.now();
+  writeFileSync(fileFor(id), JSON.stringify(rec));
+  return { id, name: rec.name, createdAt: rec.createdAt || 0, updatedAt: rec.updatedAt, dim: rec.vec?.length || 0 };
+}
+
+/**
+ * Re-record: swap in prints derived from a NEW sample, keeping the id and name.
+ *
+ * Keeping the id is the whole point. A first take is often poor — too quiet, a
+ * cough, the wrong room — and the fix should be "record that again", not "delete
+ * it, record a new one, and go re-select it everywhere". Anything already pointing
+ * at this voice keeps working and simply sounds different.
+ */
+export function replaceVoice(id, { vec, pocket = null }) {
+  const rec = getVoice(id);
+  if (!rec) return null;
+  if (!vec || vec.length !== EMBED_DIM) throw new Error(`expected a ${EMBED_DIM}-value embedding, got ${vec?.length || 0}`);
+  rec.vec = Array.from(vec, (x) => Number(x) || 0);
+  rec.updatedAt = Date.now();
+  if (pocket?.data?.length && Array.isArray(pocket.shape)) {
+    rec.pocketShape = pocket.shape;
+    const f32 = pocket.data instanceof Float32Array ? pocket.data : Float32Array.from(pocket.data);
+    writeFileSync(pocketFileFor(id), Buffer.from(f32.buffer, f32.byteOffset, f32.byteLength));
+  } else if (rec.pocketShape) {
+    // The new take produced no Pocket conditioning (its bundle is missing), so the
+    // OLD one must go — leaving it would pair a stale voice with a fresh print and
+    // the voice would change depending on which engine spoke.
+    delete rec.pocketShape;
+    rmSync(pocketFileFor(id), { force: true });
+  }
+  writeFileSync(fileFor(id), JSON.stringify(rec));
+  return {
+    id, name: rec.name, createdAt: rec.createdAt || 0, updatedAt: rec.updatedAt,
+    dim: rec.vec.length, kinds: rec.pocketShape ? [KIND_SPEECHT5, KIND_POCKET] : [KIND_SPEECHT5],
+  };
+}
+
 /** Remove one permanently. Returns whether there was anything to remove. */
 export function deleteVoice(id) {
   if (!isValidVoiceRef(id)) return false;