@chatpanel/gateway 0.6.55 → 0.6.57

package/src/sentencepiece.js

@@ -0,0 +1,184 @@
+// A minimal SentencePiece (Unigram) tokenizer — parse the .model protobuf and
+// encode with Viterbi.
+//
+// Why not a library: the reference implementation for pocket-tts ships a 4 MB
+// WASM-bundled sentencepiece build aimed at browsers. This gateway is
+// zero-runtime-dependency by design and also compiles into a Bun single-file
+// binary, so a 4 MB WASM blob for what is fundamentally a shortest-path search
+// over a 4,000-entry vocabulary is the wrong trade.
+//
+// Scope is deliberately narrow: UNIGRAM models with byte fallback, which is what
+// pocket-tts uses (4,000 pieces, each with a log-probability score, plus the 256
+// <0xNN> byte pieces). A BPE model would need a different algorithm and is
+// rejected at load rather than silently mis-tokenized.
+
+const UNK = 0, NORMAL_TYPE = 1, CONTROL = 3, BYTE = 6;
+// SentencePiece represents a space as U+2581 LOWER ONE EIGHTH BLOCK.
+const SPACE = '▁';
+
+function readVarint(buf, i) {
+  let result = 0, shift = 0;
+  for (;;) {
+    const b = buf[i++];
+    result += (b & 0x7f) * 2 ** shift;
+    if ((b & 0x80) === 0) return [result, i];
+    shift += 7;
+    if (shift > 49) throw new Error('varint too long');
+  }
+}
+
+// ModelProto { repeated SentencePiece pieces = 1; ... }
+// SentencePiece { string piece = 1; float score = 2; Type type = 3; }
+function parseModelProto(buf) {
+  const pieces = [];
+  let i = 0;
+  while (i < buf.length) {
+    let key;
+    [key, i] = readVarint(buf, i);
+    const field = key >> 3, wire = key & 7;
+    if (wire === 2) {
+      let len;
+      [len, i] = readVarint(buf, i);
+      const chunk = buf.subarray(i, i + len);
+      i += len;
+      if (field === 1) pieces.push(parsePiece(chunk));
+    } else if (wire === 0) {
+      [, i] = readVarint(buf, i);
+    } else if (wire === 5) {
+      i += 4;
+    } else if (wire === 1) {
+      i += 8;
+    } else {
+      throw new Error(`unsupported protobuf wire type ${wire}`);
+    }
+  }
+  return pieces;
+}
+
+function parsePiece(buf) {
+  let i = 0, piece = '', score = 0, type = NORMAL_TYPE;
+  while (i < buf.length) {
+    let key;
+    [key, i] = readVarint(buf, i);
+    const field = key >> 3, wire = key & 7;
+    if (wire === 2) {
+      let len;
+      [len, i] = readVarint(buf, i);
+      const val = buf.subarray(i, i + len);
+      i += len;
+      if (field === 1) piece = new TextDecoder().decode(val);
+    } else if (wire === 5) {
+      if (field === 2) score = new DataView(buf.buffer, buf.byteOffset + i, 4).getFloat32(0, true);
+      i += 4;
+    } else if (wire === 0) {
+      let v;
+      [v, i] = readVarint(buf, i);
+      if (field === 3) type = v;
+    } else {
+      break;
+    }
+  }
+  return { piece, score, type };
+}
+
+export class SentencePieceUnigram {
+  constructor(modelBytes) {
+    const pieces = parseModelProto(modelBytes);
+    if (!pieces.length) throw new Error('sentencepiece model contains no pieces');
+    // A unigram model scores every piece; a BPE model does not. Rejecting here
+    // beats producing plausible-looking but wrong token ids.
+    if (!pieces.some((p) => p.score !== 0)) {
+      throw new Error('this looks like a BPE sentencepiece model — only unigram is supported');
+    }
+    this.pieces = pieces;
+    this.vocab = new Map();
+    this.byteId = new Array(256).fill(-1);
+    this.unkId = 0;
+    for (let id = 0; id < pieces.length; id++) {
+      const { piece, type } = pieces[id];
+      if (type === UNK) this.unkId = id;
+      if (type === BYTE) {
+        const m = /^<0x([0-9A-Fa-f]{2})>$/.exec(piece);
+        if (m) this.byteId[parseInt(m[1], 16)] = id;
+        continue;
+      }
+      // Control pieces (<s>, </s>, <pad>) are addressable by id but must never be
+      // produced by encoding text — they are inserted by the caller if wanted.
+      if (type === CONTROL) continue;
+      if (!this.vocab.has(piece)) this.vocab.set(piece, id);
+    }
+    this.maxPieceLen = Math.max(...[...this.vocab.keys()].map((p) => p.length), 1);
+  }
+
+  get vocabSize() { return this.pieces.length; }
+
+  /** Text → token ids. Viterbi over piece scores, byte fallback for the rest. */
+  encodeIds(text) {
+    const norm = SPACE + String(text ?? '').normalize('NFKC').replace(/ /g, SPACE);
+    const n = norm.length;
+    // best[i] = { score, from, id } for the best segmentation of norm[0..i)
+    const best = new Array(n + 1).fill(null);
+    best[0] = { score: 0, from: -1, id: -1, bytes: null };
+
+    for (let i = 0; i < n; i++) {
+      if (!best[i]) continue;
+      let matched = false; // kept for readability of the fallback comment below
+      const limit = Math.min(n, i + this.maxPieceLen);
+      for (let j = i + 1; j <= limit; j++) {
+        const id = this.vocab.get(norm.slice(i, j));
+        if (id === undefined) continue;
+        matched = true;
+        const score = best[i].score + this.pieces[id].score;
+        if (!best[j] || score > best[j].score) best[j] = { score, from: i, id, bytes: null };
+      }
+      // Byte fallback is ALWAYS offered as an alternative, not only when nothing
+      // matched: a character can be in the vocabulary and still be the wrong split
+      // for the sentence around it. The per-byte penalty is far worse than any real
+      // piece's score, so Viterbi picks it only when it genuinely has to.
+      void matched;
+      {
+        const ch = String.fromCodePoint(norm.codePointAt(i));
+        const j = i + ch.length;
+        const bytes = new TextEncoder().encode(ch);
+        if (bytes.every((b) => this.byteId[b] >= 0)) {
+          const score = best[i].score + bytes.length * -10;
+          if (!best[j] || score > best[j].score) best[j] = { score, from: i, id: -1, bytes };
+        }
+      }
+    }
+
+    if (!best[n]) return [this.unkId];
+    const out = [];
+    for (let i = n; i > 0;) {
+      const node = best[i];
+      if (node.bytes) for (let k = node.bytes.length - 1; k >= 0; k--) out.push(this.byteId[node.bytes[k]]);
+      else out.push(node.id);
+      i = node.from;
+    }
+    return out.reverse();
+  }
+
+  /** Token ids → text. Byte pieces are reassembled before decoding as UTF-8. */
+  decodeIds(ids) {
+    const parts = [];
+    let pending = [];
+    const flush = () => {
+      if (!pending.length) return;
+      parts.push(new TextDecoder().decode(Uint8Array.from(pending)));
+      pending = [];
+    };
+    for (const id of ids) {
+      const p = this.pieces[id];
+      if (!p) continue;
+      if (p.type === BYTE) {
+        const m = /^<0x([0-9A-Fa-f]{2})>$/.exec(p.piece);
+        if (m) { pending.push(parseInt(m[1], 16)); continue; }
+      }
+      flush();
+      if (p.type === CONTROL || p.type === UNK) continue;
+      parts.push(p.piece);
+    }
+    flush();
+    return parts.join('').replace(new RegExp(SPACE, 'g'), ' ').replace(/^ /, '');
+  }
+}

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.55';
+export const VERSION = '0.6.57';
 
 // 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.
@@ -462,6 +463,23 @@ export function joinUpstream(base, pathname, search = '') {
 // short enough that a stuck download does not hold a request open forever.
 const EMBEDDER_WAIT_MS = 90_000;
 
+// Linear resample. Good enough for a voice-print sample — the encoder cares about
+// timbre, not the last decibel of fidelity — and it avoids a dependency for one
+// rate conversion.
+function resample(input, from, to) {
+  if (from === to) return input;
+  const ratio = from / to;
+  const out = new Float32Array(Math.floor(input.length / ratio));
+  for (let i = 0; i < out.length; i++) {
+    const pos = i * ratio;
+    const a = Math.floor(pos);
+    const b = Math.min(input.length - 1, a + 1);
+    const f = pos - a;
+    out[i] = input[a] * (1 - f) + input[b] * f;
+  }
+  return out;
+}
+
 const LOCAL_NAMESPACES = ['/tts', '/stt', '/ner', '/diarize', '/skills', '/config', '/logs', '/status', '/admin'];
 
 async function handleApi(req, res, { adapter, kind, pathname, search, base, destKey, destProtocol, harness, trace }, outBody, vault) {
@@ -981,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).' });
         }
@@ -991,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.
@@ -1002,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,
@@ -1023,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;
@@ -1049,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 */ }
@@ -1110,9 +1149,25 @@ export function createGateway(cfg = loadConfig()) {
               });
             }
           }
-          const vec = await diarizeEngine.embed(Float32Array.from(pcm));
-          const saved = ttsVoices.saveVoice({ name, vec });
-          console.log(`[tts] saved custom voice "${saved.name}" (${saved.dim}-d, sample discarded)`);
+          const audio = Float32Array.from(pcm);
+          const vec = await diarizeEngine.embed(audio);
+
+          // A voice print is engine-specific and the SAMPLE is about to be thrown
+          // away, so anything this voice might later need must be derived now.
+          // Pocket TTS is the engine that actually reproduces a speaker, so its
+          // conditioning is computed whenever its bundle is present — failing that
+          // is not fatal, it just means this voice works only with SpeechT5.
+          let pocket = null;
+          try {
+            const pt = await ttsEngine.pocketForEncoding({ allowDownload: cfg.tts?.allowDownload !== false, log: (m) => console.log(m) });
+            // The recorder sends 16 kHz; Mimi wants 24 kHz.
+            if (pt) pocket = await pt.encodeVoice(resample(audio, 16000, 24000));
+          } catch (e) {
+            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() });
         } catch (e) {
           return sendJson(res, 400, { error: { message: e.message, type: 'save_failed' } });
@@ -1193,7 +1248,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' } });
@@ -1206,7 +1261,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
@@ -1216,8 +1277,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',
@@ -1225,7 +1291,23 @@ export function createGateway(cfg = loadConfig()) {
               },
             });
           }
-          speakerEmbedding = rec.vec;
+          // Which print to hand over depends on the engine: Pocket TTS takes its
+          // Mimi conditioning, SpeechT5 the 512-d x-vector. A voice saved before
+          // the pocket bundle existed has only the latter.
+          if (ttsEngine.isPocket()) {
+            const pk = ttsVoices.getPocketVoice(customId);
+            if (!pk) {
+              return sendJson(res, 409, {
+                error: {
+                  message: 'this voice was saved without a Pocket TTS conditioning — record it again with Pocket TTS selected',
+                  type: 'voice_kind_missing',
+                },
+              });
+            }
+            speakerEmbedding = pk;
+          } else {
+            speakerEmbedding = rec.vec;
+          }
           useVoice = `custom:${customId}`;
         } else if (customId) {
           // Explicitly asked for a recorded voice this model cannot use — say so.
@@ -1238,7 +1320,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

@@ -24,8 +24,9 @@ import { ensureLib, modelRoot } from './ner-engine.js';
 import { runtimeDtype, runtimeName, DTYPE_SUFFIX } from './model-runtime.js';
 import {
   DEFAULT_TTS_MODEL, DEFAULT_TTS_VOICE, STYLE_DIM, MAX_PHONEME_TOKENS,
-  ttsModelDtype, isKnownTtsModel, isValidVoiceId, voiceLang,
+  ttsModelDtype, isKnownTtsModel, isValidVoiceId, voiceLang, ttsModelEngine, ttsModel,
 } from './tts-models.js';
+import { bundleOnDisk as pocketBundleOnDisk } from './pocket-tts-engine.js';
 
 // Kokoro's rate. Kept as a named export because it is the default and several
 // callers want a number before anything is loaded — but it is NOT universal: a
@@ -43,6 +44,8 @@ let _progress = null;
 let _initPromise = null;
 let _arch = null;         // 'style-tts2' (Kokoro) | 'vits' (MMS) | 'speecht5' (custom voices)
 let _vocoder = null;      // speecht5 only — mel → waveform
+let _pocket = null;       // pocket-tts only — its own PocketTTS instance
+let _encoder = null;      // a PocketTTS kept ONLY to encode voices, never to speak
 let _rate = SAMPLE_RATE;  // the ACTIVE model's output rate
 const _voices = new Map(); // voice id → Float32Array style bank
 
@@ -51,12 +54,40 @@ const _voices = new Map(); // voice id → Float32Array style bank
 // forward pass with a shape error nobody can act on.
 export const SUPPORTED_ARCH = { style_text_to_speech_2: 'style-tts2', vits: 'vits', speecht5: 'speecht5' };
 
+// Pocket TTS is not a transformers.js model — it is five raw ONNX graphs with a
+// hand-written generation loop, exactly like parakeet on the STT side — so it is
+// dispatched by catalog id rather than by a transformers config.model_type.
+export const POCKET_ARCH = 'pocket-tts';
+
 // SpeechT5 is the only architecture here that takes a SPEAKER EMBEDDING, which is
 // what makes a custom voice possible at all: Kokoro's voices are fixed style banks
 // and VITS is single-speaker, so neither can be pointed at a person. It needs a
 // separate vocoder (mel → waveform), hence the extra model id.
 export const SPEECHT5_VOCODER = 'Xenova/speecht5_hifigan';
-export function supportsCustomVoices() { return _arch === 'speecht5'; }
+// Both engines that can be pointed at a person. Pocket TTS is the one built for
+// it; SpeechT5 is kept because it is small and already downloaded for anyone who
+// 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
+ * model is currently speaking. Saving a voice has to derive its conditioning while
+ * the sample still exists, and that must not silently switch the active engine out
+ * from under a conversation in progress.
+ */
+export async function pocketForEncoding({ allowDownload = true, log = () => {} } = {}) {
+  if (_pocket) return _pocket;
+  const { PocketTTS, bundleOnDisk, DEFAULT_BUNDLE } = await import('./pocket-tts-engine.js');
+  if (!bundleOnDisk(DEFAULT_BUNDLE) && !allowDownload) return null;
+  if (_encoder) return _encoder;
+  const pt = new PocketTTS();
+  await pt.load(DEFAULT_BUNDLE, { log });
+  _encoder = pt;
+  return pt;
+}
 
 export function arch() { return _arch; }
 export function sampleRate() { return _rate; }
@@ -79,6 +110,11 @@ export function modelDir(modelId) {
 // Present = the EXACT ONNX file this runtime will load, plus the tokenizer. Both
 // non-empty: a truncated download must not read as installed.
 export function modelOnDisk(modelId = _model || DEFAULT_TTS_MODEL, dtype = ttsModelDtype(modelId) || runtimeDtype()) {
+  // Pocket TTS keeps a bundle of five graphs under its own directory, not a single
+  // transformers-style onnx/ folder. bundleOnDisk is a pure fs predicate — the
+  // heavy onnxruntime import inside that module is dynamic — so importing it
+  // statically costs nothing.
+  if (ttsModelEngine(modelId) === POCKET_ARCH) return pocketBundleOnDisk(ttsModel(modelId)?.bundle);
   const dir = modelDir(modelId);
   const suffix = DTYPE_SUFFIX[dtype] ?? '';
   const need = [join(dir, 'onnx', `model${suffix}.onnx`), join(dir, 'tokenizer.json')];
@@ -104,6 +140,10 @@ export function init(cfg = {}) {
 }
 
 async function loadModel(modelId, { log = () => {}, allowDownload = true, dtype: dtypeOverride = null } = {}) {
+  // Pocket TTS has its own loader (raw onnxruntime, its own bundle layout), so it
+  // is routed before any transformers.js machinery is touched.
+  if (ttsModelEngine(modelId) === POCKET_ARCH) return loadPocket(modelId, { log, allowDownload });
+
   const prevNet = _net, prevModel = _model;
   let lib;
   try {
@@ -190,6 +230,36 @@ async function loadModel(modelId, { log = () => {}, allowDownload = true, dtype:
   }
 }
 
+async function loadPocket(modelId, { log = () => {}, allowDownload = true } = {}) {
+  const prevArch = _arch, prevPocket = _pocket, prevModel = _model;
+  const { PocketTTS, bundleOnDisk, DEFAULT_BUNDLE, SAMPLE_RATE: PR } = await import('./pocket-tts-engine.js');
+  const bundle = ttsModel(modelId)?.bundle || DEFAULT_BUNDLE;
+  if (!bundleOnDisk(bundle) && !allowDownload) {
+    _state = 'error'; _err = 'model not on disk and downloads disabled';
+    return false;
+  }
+  _state = bundleOnDisk(bundle) ? 'loading' : 'downloading';
+  if (_state === 'downloading') _progress = { model: modelId, file: null, pct: 0 };
+  try {
+    const pt = new PocketTTS();
+    await pt.load(bundle, {
+      log,
+      onProgress: ({ file, pct }) => { _progress = { model: modelId, file, pct }; },
+    });
+    _pocket = pt; _net = pt; _tok = null; _vocoder = null;
+    _model = modelId; _arch = POCKET_ARCH; _dtype = 'int8'; _rate = PR;
+    _state = 'ready'; _err = null; _progress = null;
+    return true;
+  } catch (e) {
+    // A failed switch keeps whatever was working, same as every other engine here.
+    _pocket = prevPocket; _arch = prevArch; _model = prevModel;
+    _state = prevPocket || _net ? 'ready' : 'error';
+    _err = e.message; _progress = null;
+    log(`[pocket-tts] load failed (${e.message})`);
+    return false;
+  }
+}
+
 export async function setModel(modelId, { onLog = () => {}, allowDownload = true, dtype = 'auto' } = {}) {
   const want = dtype && dtype !== 'auto' ? dtype : (ttsModelDtype(modelId) || runtimeDtype());
   if (modelId === _model && isReady() && _dtype === want) return true;
@@ -288,6 +358,15 @@ export async function synthChunk(text, { voice = DEFAULT_TTS_VOICE, speed = 1, s
     return out.waveform.data;
   }
 
+  // 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) {
+    // 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 —
   // it is the one architecture here that can be pointed at a person's voice.
   // Without an embedding there is no voice to speak in, so this refuses rather
@@ -324,6 +403,9 @@ export async function synthChunk(text, { voice = DEFAULT_TTS_VOICE, speed = 1, s
 
 /** Synthesize arbitrary-length text, chunk by chunk. `onChunk` sees each as it lands. */
 export async function synth(text, { voice = DEFAULT_TTS_VOICE, speed = 1, speakerEmbedding = null, onChunk = null } = {}) {
+  // Pocket TTS splits internally against its own token ceiling, so splitting again
+  // here would cut sentences twice and reset its state mid-thought.
+  if (_arch === POCKET_ARCH) return synthChunk(text, { voice, speed, speakerEmbedding });
   const chunks = splitSentences(text);
   const out = [];
   for (const c of chunks) {
@@ -366,6 +448,6 @@ export function toWav(pcm, sampleRate = SAMPLE_RATE) {
 
 export function _reset() {
   _state = 'off'; _model = null; _net = null; _tok = null; _dtype = null;
-  _err = null; _progress = null; _initPromise = null; _arch = null; _rate = SAMPLE_RATE; _vocoder = null;
+  _err = null; _progress = null; _initPromise = null; _arch = null; _rate = SAMPLE_RATE; _vocoder = null; _pocket = null; _encoder = null;
   _voices.clear();
 }

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.
@@ -55,6 +76,28 @@ export const TTS_MODEL_CATALOG = [
     voices: true,
     note: 'The Mandarin-tuned Kokoro. Same engine and voice mechanism as v1.0.',
   },
+  {
+    // The one model here BUILT for cloning. Its Mimi encoder turns a sample into a
+    // conditioning the model generates from directly, rather than borrowing a
+    // voice print from a space it was not trained on — which is why it reproduces
+    // a speaker where SpeechT5 merely produces a consistent stranger. Also the
+    // fastest: measured 8-9x realtime at int8, against Kokoro's 2.1x.
+    id: 'kyutai/pocket-tts',
+    label: 'Pocket TTS — clone your voice',
+    lang: 'English',
+    tier: 'accurate',
+    arch: 'pocket-tts',
+    bundle: 'english_2026-04',
+    approxMB: 146,
+    ramMB: 700,
+    sampleRate: 24000,
+    voices: true,           // eight built-in speakers (optional 52 MB voices.bin)
+    customVoices: true,     // …and it can speak as YOU
+    recommended: true,
+    // 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',
     label: 'SpeechT5 — your own voice',
@@ -74,7 +117,7 @@ export const TTS_MODEL_CATALOG = [
     sampleRate: 16000,
     voices: false,          // no built-in voices…
     customVoices: true,     // …but it is the ONE model here that can use yours
-    note: 'The only model here that speaks in a voice you record. Rougher than Kokoro, and the match is approximate — see the note under Your voices.',
+    note: 'Speaks using a voice you record — but it will NOT sound like you. It borrows pitch and timbre in a general way and produces a consistent voice of its own. Kokoro sounds better if you do not need a personal voice.',
   },
   {
     // One MMS entry so the second architecture is DISCOVERABLE from the list rather
@@ -137,6 +180,11 @@ export function ttsModelEngine(id) {
   return ttsModel(id)?.arch || 'style-tts2';
 }
 
+// The bundle a pocket-tts catalog entry uses (its language pack).
+export function ttsModelBundle(id) {
+  return ttsModel(id)?.bundle || null;
+}
+
 // Does this catalog entry have selectable voices? Kokoro picks one from a style
 // bank; VITS/MMS is single-speaker. Unknown (a searched model) resolves at load.
 export function ttsModelHasVoices(id) {
@@ -150,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;
 }