@tablefolk/voice 0.0.0-stage → 0.1.0

package/breeze-web-worker.js

@@ -0,0 +1,177 @@
+// Breeze TTS 2 in the browser: Breeze-TTS-2.cpp (HoppouAI, Apache-2.0)
+// compiled to WebAssembly with ggml's WebGPU backend (tools/breeze-web/), as
+// a speech worker for pocket-tts-manager.js (the same messages as
+// pocket18-worker.js):
+//   in:  load, set_audio_port, encode_voice {voiceId, audio, text, cacheKey},
+//        generate {text, voice, instruction}, stop, delete_voice
+//   out: status, runtime_info, bundle_loaded, loaded, voice_encoded,
+//        generation_started, audio_chunk_meta, generation_metrics,
+//        stream_ended, error
+//
+// The model (BreezeBlue's Breeze TTS 2, research and non-commercial licence;
+// HoppouAI's q4_k-dd2 GGUF, 2.46 GB) comes once from the R2 mirror
+// (breeze-tts-2/: 64 MiB parts, four at a time over the four hostnames,
+// each written at its offset) into this origin's private file system (OPFS),
+// then is mounted read-only (WORKERFS): the loader reads it tensor by tensor
+// onto the GPU, never all of it into WebAssembly memory.
+// A library voice is encoded once from its sample and transcript; the codes
+// are kept in IndexedDB.
+const BASES = ['https://geebr-models.mindroot.io', 'https://geebr-models-2.mindroot.io', 'https://geebr-models-3.mindroot.io', 'https://geebr-models-4.mindroot.io'];
+const MODEL = 'breeze-tts-2-q4_k-dd2.gguf', DIR = 'tablefolk-breeze';
+// the same file on Hugging Face: pages other than tablefolk.world download from there
+// (the load message's mirror: false), in 64 MiB ranges like the mirror's parts
+const HF_URL = 'https://huggingface.co/HoppouAI/Breeze-TTS-2.cpp/resolve/main/' + MODEL;
+let useMirror = true;
+let M = null, port = null, stopPtr = 0, loading = null;
+// views of the module's memory made fresh each time (they go stale when it grows)
+const f32 = () => new Float32Array(M.wasmMemory.buffer), i32 = () => new Int32Array(M.wasmMemory.buffer);
+const voices = new Map();   // voiceId -> { codes: Int32Array, frames, text }
+const status = (text, state = 'loading') => postMessage({ type: 'status', status: text, state });
+
+async function opfsModel(onProgress) {
+  const root = await navigator.storage.getDirectory(), dir = await root.getDirectoryHandle(DIR, { create: true });
+  const man = useMirror ? await (await fetch(`${BASES[0]}/breeze-tts-2/${MODEL}.parts.json`)).json() : await (async () => {
+    const r = await fetch(HF_URL, { headers: { Range: 'bytes=0-0' } }); await r.body?.cancel();
+    const size = Number(r.headers.get('Content-Range')?.split('/')[1]) || 0; if (!size) throw new Error('Breeze TTS 2: Hugging Face gave no size');
+    const partSize = 64 * 2 ** 20; return { size, partSize, parts: Array.from({ length: Math.ceil(size / partSize) }, (_, i) => i) };
+  })();
+  const fh = await dir.getFileHandle(MODEL, { create: true });
+  let file = await fh.getFile();
+  if (file.size === man.size && (await dir.getFileHandle(MODEL + '.ok').then(() => true, () => false))) return file;
+  try { await dir.removeEntry(MODEL + '.ok'); } catch {}
+  const h = await fh.createSyncAccessHandle();
+  try {
+    h.truncate(man.size);
+    let done = 0, next = 0;
+    const one = async (i) => {
+      for (let t = 0; ; t++) {
+        try {
+          const r = useMirror ? await fetch(`${BASES[i % 4]}/breeze-tts-2/${man.parts[i]}`)
+            : await fetch(HF_URL, { headers: { Range: `bytes=${i * man.partSize}-${Math.min((i + 1) * man.partSize, man.size) - 1}` } });
+          if (!r.ok) throw new Error('HTTP ' + r.status);
+          const buf = new Uint8Array(await r.arrayBuffer());
+          h.write(buf, { at: i * man.partSize }); done += buf.length; onProgress(done, man.size); return;
+        } catch (e) { if (t >= 3) throw new Error(`model part ${i}: ${e.message}`); await new Promise(r => setTimeout(r, 1500 * (t + 1))); }
+      }
+    };
+    await Promise.all([0, 1, 2, 3].map(async () => { while (next < man.parts.length) await one(next++); }));
+    h.flush();
+  } finally { h.close(); }
+  await dir.getFileHandle(MODEL + '.ok', { create: true });
+  return fh.getFile();
+}
+
+// voice codes kept between visits
+const db = () => new Promise((res, rej) => { const q = indexedDB.open('tablefolk-breeze-voices', 1); q.onupgradeneeded = () => q.result.createObjectStore('codes'); q.onsuccess = () => res(q.result); q.onerror = () => rej(q.error); });
+async function cacheGet(key) { try { const d = await db(); return await new Promise(r => { const q = d.transaction('codes').objectStore('codes').get(key); q.onsuccess = () => r(q.result || null); q.onerror = () => r(null); }); } catch { return null; } }
+async function cachePut(key, v) { try { const d = await db(); d.transaction('codes', 'readwrite').objectStore('codes').put(v, key); } catch {} }
+
+async function load(opts = {}) {
+  if (M) return;
+  if (opts.mirror === false) useMirror = false;
+  // what it needs, checked before the 2.5 GB download (browser-check.js has the same rules)
+  if (typeof WebAssembly.Suspending !== 'function') throw new Error('Breeze TTS 2 failed: this browser has no JSPI (WebAssembly.Suspending); it needs Chrome or Edge 137+, Safari 27+ or Firefox 153+');
+  if (!opts.allowCpu) {
+    const a = await navigator.gpu?.requestAdapter({ powerPreference: 'high-performance' }).catch(() => null);
+    if (!a) throw new Error('Breeze TTS 2 failed: no WebGPU in this browser\'s workers');
+    if (!a.features.has('shader-f16')) throw new Error('Breeze TTS 2 failed: the graphics card offers no WebGPU shader-f16' + (/linux/i.test(navigator.userAgent) && a.info?.vendor === 'nvidia' ? ' (Chrome on Linux with NVIDIA: start it with --enable-dawn-features=vulkan_enable_f16_on_nvidia)' : ''));
+  }
+  status('Breeze TTS 2: checking the model…');
+  const t0 = performance.now();
+  const file = await opfsModel((n, total) => status(`Downloading Breeze TTS 2 ${Math.floor(100 * n / total)}% (${(n / 2 ** 30).toFixed(2)} / ${(total / 2 ** 30).toFixed(2)} GB, once)`));
+  status('Breeze TTS 2: loading onto the GPU…');
+  const create = (await import('./breeze-web/breeze.mjs')).default;
+  M = await create({ print: s => console.log('[breeze]', s), printErr: s => console.warn('[breeze]', s) });
+  M.FS.mkdir('/m'); M.FS.mount(M.WORKERFS || M.FS.filesystems.WORKERFS, { files: [file] }, '/m');
+  const rc = await M.ccall('tf_init', 'number', ['string'], ['/m/' + MODEL], { async: true });
+  if (rc !== 0) { const err = M.UTF8ToString(M._tf_error()); M = null; throw new Error('Breeze TTS 2 failed to load: ' + err); }
+  stopPtr = M._tf_stop_flag();
+  M.onAudio = pcm => onAudio(pcm);
+  const backend = M.UTF8ToString(M._tf_backend());
+  console.info('[breeze] devices:', M.UTF8ToString(M._tf_devices()), '| using', backend);
+  // ggml's WebGPU backend needs the shader-f16 feature: Chrome on Linux with
+  // NVIDIA's Vulkan driver hides it unless started with
+  // --enable-dawn-features=vulkan_enable_f16_on_nvidia. On the CPU a line takes minutes.
+  if (!/webgpu/i.test(backend) && !opts.allowCpu) { M = null; throw new Error('Breeze TTS 2 needs WebGPU shader-f16 in this browser (Chrome on Linux with NVIDIA: start it with --enable-dawn-features=vulkan_enable_f16_on_nvidia); without it, it runs only on the CPU (far too slow)'); }
+  postMessage({ type: 'runtime_info', data: { backend: 'Breeze TTS 2 in this browser (' + backend + ')' } });
+  postMessage({ type: 'bundle_loaded', sampleRate: M._tf_sample_rate() || 24000 });
+  postMessage({ type: 'loaded', loadMs: Math.round(performance.now() - t0) });
+  status('Breeze TTS 2 ready (' + backend + ')', 'ready');
+}
+
+async function encode({ voiceId, audio, text, cacheKey }) {
+  if (!text) { voices.set(voiceId, null); return; }   // no transcript: it can only design a voice
+  let v = cacheKey && await cacheGet(cacheKey);
+  if (!v) {
+    const a = audio instanceof Float32Array ? audio : Float32Array.from(audio || []);
+    const p = M._malloc(a.length * 4); f32().set(a, p >>> 2);
+    const frames = await M.ccall('tf_encode', 'number', ['number', 'number'], [p, a.length], { async: true });
+    M._free(p);
+    if (frames < 0) throw new Error('voice encode: ' + M.UTF8ToString(M._tf_error()));
+    const n = M._tf_codes_len(), ptr = M._tf_codes();
+    v = { codes: i32().slice(ptr >>> 2, (ptr >>> 2) + n), frames, text };
+    if (cacheKey) cachePut(cacheKey, v);
+  }
+  voices.set(voiceId, v);
+}
+
+let gen = null;
+function onAudio(pcm) {
+  if (!gen) return;
+  if (gen.first == null) gen.first = performance.now() - gen.t0;
+  gen.samples += pcm.length;
+  // the warm-up: nothing is played, and a second of audio is enough
+  if (gen.silent) { if (gen.samples > 24000 && stopPtr) i32()[stopPtr >>> 2] = 1; return; }
+  const metrics = { chunkRtfx: gen.samples / 24000 / ((performance.now() - gen.t0) / 1000) };
+  if (port) { port.postMessage({ type: 'audio', data: pcm }, [pcm.buffer]); postMessage({ type: 'audio_chunk_meta', metrics }); }
+  else postMessage({ type: 'audio_chunk', data: pcm.buffer, metrics }, [pcm.buffer]);
+}
+
+async function generate({ text, voice, instruction, silent = false }) {
+  if (!String(text || '').trim()) { if (!silent) postMessage({ type: 'stream_ended' }); return; }
+  const v = voices.get(String(voice).replace(/^custom:/, '')) || null;
+  gen = { t0: performance.now(), samples: 0, first: null, silent };
+  if (!silent) { port?.postMessage({ type: 'reset' }); postMessage({ type: 'generation_started', data: { time: gen.t0, sourceSampleRate: 24000 } }); }
+  let cp = 0;
+  if (v) { cp = M._malloc(v.codes.length * 4); i32().set(v.codes, cp >>> 2); }
+  i32()[stopPtr >>> 2] = 0;
+  const rc = await M.ccall('tf_generate', 'number',
+    ['string', 'string', 'string', 'number', 'number', 'number', 'number', 'number', 'number', 'number'],
+    [String(text), v ? '' : (instruction || 'A warm, natural speaking voice. Speak clearly and naturally.'), v ? v.text : '', cp, v ? v.codes.length : 0, v ? v.frames : 0, 7, 1, 4, 25],
+    { async: true });
+  if (cp) M._free(cp);
+  const g = gen; gen = null;
+  if (rc === 1) throw new Error('Breeze: ' + M.UTF8ToString(M._tf_error()));
+  const secs = (performance.now() - g.t0) / 1000;
+  if (silent) { console.log(`[breeze] warm-up: first audio ${Math.round(g.first || 0)} ms, ${secs.toFixed(1)} s`); return; }
+  // rtfx: speed once audio has started (the wait before it is firstAudioMs). It sets how much is held before playing
+  // (holdFor), and counting the wait as slowness made every line wait seconds longer than it had to.
+  const after = Math.max(.001, secs - (g.first || 0) / 1000);
+  postMessage({ type: 'generation_metrics', metrics: { rtfx: g.samples / 24000 / after, overallRtfx: g.samples / 24000 / secs, genTime: secs, totalTime: secs, audioDuration: g.samples / 24000, firstAudioMs: g.first } });
+  if (rc === 0) { port?.postMessage({ type: 'stream-ended' }); postMessage({ type: 'stream_ended' }); }
+}
+
+// one job at a time (the model has one cache); stop goes straight through
+let chain = Promise.resolve();
+self.onmessage = e => {
+  const { type, data = {} } = e.data || {};
+  if (type === 'set_audio_port') { port = e.ports?.[0] || null; return; }
+  if (type === 'stop') { if (M && stopPtr) i32()[stopPtr >>> 2] = 1; return; }
+  if (type === 'delete_voice') { voices.delete(data.voiceId); return; }
+  if (type === 'set_language') { postMessage({ type: 'voices_loaded', voices: [], language: 'english' }); return; }
+  chain = chain.then(async () => {
+    try {
+      if (type === 'load') return await (loading ||= load(data).catch(err => { loading = null; throw err; }));
+      if (type === 'encode_voice' || type === 'load_voice_state' || type === 'load_voice_bin') { if (type === 'encode_voice') await encode(data); postMessage({ type: 'voice_encoded', voiceId: data.voiceId }); return; }
+      if (type === 'generate') return await generate(data);
+      // a short line made and thrown away, so the first real one starts at full speed
+      if (type === 'warmup') { await generate({ ...data, silent: true }); postMessage({ type: 'warmed' }); return; }
+      if (type === 'debug_stages') { const p = await M.ccall('tf_stages', 'number', [], [], { async: true }); postMessage({ type: 'debug_stages', text: M.UTF8ToString(p) }); return; }
+      if (type === 'debug_matvec') { const p = await M.ccall('tf_matvec_check', 'number', ['number'], [data.repeats || 20], { async: true }); postMessage({ type: 'debug_matvec', text: M.UTF8ToString(p) }); return; }
+      // codes encoded natively ahead of time (assets/voices/breeze-codes): no encoder, and closer to native
+      if (type === 'voice_codes') { voices.set(data.voiceId, { codes: data.codes, frames: data.frames, text: data.text }); postMessage({ type: 'voice_encoded', voiceId: data.voiceId }); return; }
+      if (type === 'debug_trace') { const c = data.codes ? Int32Array.from(data.codes) : new Int32Array(1); const cp = M._malloc(c.length * 4); i32().set(c, cp >>> 2); const p = await M.ccall('tf_trace', 'number', ['number', 'number', 'number', 'string', 'number', 'number'], [cp, c.length, data.frames || 0, data.text || '', data.useRef ? 1 : 0, data.steps || 40], { async: true }); M._free(cp); postMessage({ type: 'debug_trace', text: M.UTF8ToString(p) }); return; }
+      if (type === 'debug_hash') { const p = await M.ccall('tf_hash_tensors', 'number', [], [], { async: true }); postMessage({ type: 'debug_hash', text: M.UTF8ToString(p) }); return; }
+    } catch (err) { console.error('[breeze]', err?.stack || err); postMessage({ type: 'error', error: String(err?.message || err) }); }
+  });
+};

package/index.js

@@ -0,0 +1,161 @@
+// @tablefolk/voice -- text to speech in the browser, nothing sent anywhere:
+//   pocket-18m   Pocket-TTS small (Kyutai, CC-BY-4.0): ~40 MB, English, on the processor; phones
+//   pocket-100m  Pocket-TTS (~120 MB, five languages), on the processor
+//   breeze-web   Breeze TTS 2 (3B, WebGPU, a 2.5 GB download once): far better, needs a
+//                graphics card with ~3.5 GB free, shader-f16 and JSPI. Its weights are for
+//                research and non-commercial use only (BreezeBlue's licence).
+//   browser      the browser's own speechSynthesis (no download)
+//
+//   import { createVoice, chooseEngine } from '@tablefolk/voice';
+//   const v = await createVoice({ engine: 'auto', onStatus: s => console.log(s) });
+//   v.engine, v.why                         // 'pocket-18m', 'a phone: the small model'
+//   await v.speak('Well met, traveller.', { voice: 'alba' })   // resolves when it has been heard
+//   for await (const pcm of v.stream('Hello')) ...   // Float32Array chunks at v.sampleRate (no playback)
+//   v.voices                                // the built-in voice names
+//   await v.cloneVoice('me', pcm24k, 'the words said in it')   // Pocket: audio alone; Breeze: with its transcript
+//   v.stop(); v.unload(); v.level()          // level: loudness now (for a talking mouth)
+//
+// 'auto': Breeze in the browser when the device has room for it beside what
+// else it runs (pass freeGB, the graphics memory left) and allowBreeze is
+// true (default; false for a commercial product); else Pocket-TTS small. The
+// models download from Hugging Face, or Tablefolk's mirror on tablefolk.world.
+import { createWorker, mirrorAllowed, note } from '@tablefolk/models';
+import { detectHardware, usableGB } from '@tablefolk/device';
+
+export const ENGINES = {
+  'pocket-18m': { label: 'Pocket-TTS small (18M, English)', worker: 'pocket18-worker.js', size: '~40 MB' },
+  'pocket-100m': { label: 'Pocket-TTS (100M, 5 languages)', worker: 'pocket-worker.js', size: '~120 MB', languages: true },
+  'breeze-web': { label: 'Breeze TTS 2 (3B, WebGPU; non-commercial licence)', worker: 'breeze-web-worker.js', size: '2.5 GB', needGB: 3.5, nonCommercial: true },
+  'browser': { label: 'the browser\'s speech', size: 'none' },
+};
+export const POCKET_VOICES = ['alba', 'azelma', 'cosette', 'eponine', 'fantine', 'javert', 'jean', 'marius'];
+
+// The engine for this device, and why. freeGB: graphics memory left beside
+// the page's other models (default: all of what @tablefolk/device finds usable).
+export async function chooseEngine({ allowBreeze = true, freeGB = null, preferBreeze = true } = {}) {
+  const hw = await detectHardware().catch(() => null);
+  if (hw && (hw.cls === 'phone' || hw.cls === 'tablet')) return { engine: 'pocket-18m', why: 'a phone or tablet: the small model' };
+  if (!allowBreeze || !preferBreeze) return { engine: 'pocket-18m', why: allowBreeze ? 'the small model' : 'Breeze not allowed here (its licence is non-commercial)' };
+  const no = await breezeWhyNot(hw, freeGB);
+  return no ? { engine: 'pocket-18m', why: 'Breeze can\'t run here: ' + no } : { engine: 'breeze-web', why: 'the graphics card has room for Breeze' };
+}
+export async function breezeWhyNot(hw = null, freeGB = null) {
+  if (typeof WebAssembly.Suspending !== 'function') return 'no JSPI in this browser';
+  const a = await navigator.gpu?.requestAdapter({ powerPreference: 'high-performance' }).catch(() => null);
+  if (!a) return 'no WebGPU';
+  if (!a.features.has('shader-f16')) return 'no shader-f16 on this graphics card';
+  hw ||= await detectHardware().catch(() => null);
+  const free = freeGB ?? usableGB(hw);
+  if (free == null) return 'the graphics memory is not known';
+  if (free < ENGINES['breeze-web'].needGB) return `${free} GB of graphics memory free; Breeze wants ${ENGINES['breeze-web'].needGB}`;
+  return '';
+}
+
+export async function createVoice({ engine = 'auto', voice = null, language = null, onStatus = () => {}, audioContext = null, allowBreeze = true, freeGB = null } = {}) {
+  const pick = engine === 'auto' ? await chooseEngine({ allowBreeze, freeGB }) : { engine, why: 'asked for' };
+  const E = ENGINES[pick.engine]; if (!E) throw new Error('unknown voice engine ' + pick.engine);
+  note('voice', `${E.label}: ${pick.why}`);
+  if (pick.engine === 'browser') return browserVoice(pick);
+
+  const w = createWorker(new URL('./' + E.worker, import.meta.url));
+  let sampleRate = 24000, voices = [], defaultVoice = voice;
+  let sink = null;   // the stream being read: { push(Float32Array), end(), fail(e) }
+  const waitLoad = new Promise((resolve, reject) => {
+    w.onmessage = e => {
+      const m = e.data || {};
+      if (m.type === 'status') onStatus(m.status);
+      else if (m.type === 'bundle_loaded') sampleRate = m.sampleRate || sampleRate;
+      else if (m.type === 'voices_loaded') { voices = m.voices || voices; defaultVoice ||= m.defaultVoice; }
+      else if (m.type === 'loaded') resolve();
+      else if (m.type === 'generation_started') sampleRate = m.data?.sourceSampleRate || sampleRate;
+      else if (m.type === 'audio_chunk') sink?.push(new Float32Array(m.data));
+      else if (m.type === 'stream_ended') sink?.end();
+      else if (m.type === 'voice_encoded') sink?.encoded?.(m.voiceName);
+      else if (m.type === 'error') { const err = new Error(m.error || 'voice error'); if (sink) sink.fail(err); else reject(err); }
+    };
+    w.onerror = e => reject(new Error(e.message || 'voice worker failed'));
+  });
+  w.postMessage({ type: 'load', data: { mirror: mirrorAllowed(), language: language || undefined, allowCpu: false } });
+  await waitLoad;
+  onStatus(`${E.label} ready`);
+
+  let queue = Promise.resolve();
+  // PCM pieces of one line (one line at a time: the worker generates one)
+  function stream(text, { voice: v = defaultVoice, instruction } = {}) {
+    const chunks = [], waiters = []; let done = false, error = null;
+    const wake = () => { while (waiters.length && (chunks.length || done || error)) waiters.shift()(); };
+    const run = () => new Promise(res => {
+      sink = { push: c => { chunks.push(c); wake(); }, end: () => { done = true; sink = null; wake(); res(); }, fail: e => { error = e; sink = null; wake(); res(); } };
+      w.postMessage({ type: 'generate', data: { text, voice: v, instruction } });
+    });
+    queue = queue.then(run, run);
+    return { [Symbol.asyncIterator]() { return this; },
+      async next() {
+        while (!chunks.length && !done && !error) await new Promise(r => waiters.push(r));
+        if (chunks.length) return { value: chunks.shift(), done: false };
+        if (error) throw error;
+        return { value: undefined, done: true };
+      } };
+  }
+
+  // playback: chunks scheduled back to back
+  let ctx = audioContext, gain = null, analyser = null, levelBuf = null, playing = new Set(), stopped = 0;
+  function audio() {
+    if (!ctx) ctx = new AudioContext();
+    if (!gain) { gain = ctx.createGain(); analyser = ctx.createAnalyser(); analyser.fftSize = 1024; levelBuf = new Float32Array(analyser.fftSize); gain.connect(analyser); analyser.connect(ctx.destination); }
+    return ctx;
+  }
+  async function speak(text, opts = {}) {
+    const c = audio(); if (c.state === 'suspended') await c.resume().catch(() => {});
+    const gen = stopped; let at = c.currentTime + 0.05, last = null;
+    for await (const pcm of stream(text, opts)) {
+      if (gen !== stopped) break;
+      const b = c.createBuffer(1, pcm.length, sampleRate); b.copyToChannel(pcm, 0);
+      const s = c.createBufferSource(); s.buffer = b; s.connect(gain);
+      at = Math.max(at, c.currentTime + 0.02); s.start(at); at += b.duration;
+      playing.add(s); s.onended = () => playing.delete(s); last = s;
+    }
+    if (last && gen === stopped) await new Promise(r => { last.addEventListener('ended', r, { once: true }); });
+  }
+  return {
+    engine: pick.engine, why: pick.why, label: E.label,
+    get voices() { return voices.map(v => typeof v === 'string' ? v : v.name || v.id).filter(Boolean); },
+    get sampleRate() { return sampleRate; },
+    speak, stream,
+    setVolume(v) { audio(); gain.gain.value = v; },
+    level() { if (!analyser) return 0; analyser.getFloatTimeDomainData(levelBuf); let s = 0; for (const v of levelBuf) s += v * v; return Math.sqrt(s / levelBuf.length); },
+    // a voice of your own: 24 kHz mono audio (a few seconds); Breeze also wants the words said in it
+    cloneVoice(id, audio24k, text = '') {
+      return new Promise((resolve, reject) => {
+        const prev = sink;
+        sink = { encoded: name => { sink = prev; resolve(name); }, fail: e => { sink = prev; reject(e); }, push() {}, end() {} };
+        const a = new Float32Array(audio24k);
+        w.postMessage({ type: 'encode_voice', data: { voiceId: id, audio: a, text, cacheKey: id } }, [a.buffer]);
+      });
+    },
+    stop() { stopped++; w.postMessage({ type: 'stop' }); for (const s of playing) { try { s.stop(); } catch {} } playing.clear(); },
+    unload() { this.stop(); w.terminate(); },
+  };
+}
+
+// the browser's speechSynthesis behind the same methods (no stream: it plays itself)
+function browserVoice(pick) {
+  const S = globalThis.speechSynthesis;
+  if (!S) throw new Error('no speechSynthesis in this browser');
+  const list = () => S.getVoices();
+  return {
+    engine: 'browser', why: pick.why, label: ENGINES.browser.label, sampleRate: null,
+    get voices() { return list().map(v => v.name); },
+    speak(text, { voice } = {}) {
+      return new Promise((resolve, reject) => {
+        const u = new SpeechSynthesisUtterance(text);
+        const v = voice && list().find(x => x.name === voice); if (v) u.voice = v;
+        u.onend = () => resolve(); u.onerror = e => e.error === 'interrupted' || e.error === 'canceled' ? resolve() : reject(new Error(e.error));
+        S.speak(u);
+      });
+    },
+    stream() { throw new Error('the browser\'s speech plays itself: use speak()'); },
+    level: () => 0, setVolume() {}, cloneVoice() { throw new Error('the browser\'s speech has no custom voices'); },
+    stop() { S.cancel(); }, unload() { S.cancel(); },
+  };
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@tablefolk/voice",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Text to speech in the browser: Pocket-TTS (small, CPU) and Breeze TTS 2 (WebGPU), chosen for the device, or the browser's speechSynthesis.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./*": "./*"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runvnc/tablefolk.git",
+    "directory": "libs/voice"
+  },
+  "homepage": "https://github.com/runvnc/tablefolk/tree/main/libs/voice",
+  "keywords": [
+    "tablefolk",
+    "browser",
+    "tts",
+    "speech",
+    "pocket-tts",
+    "breeze",
+    "webgpu"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@tablefolk/models": "^0.1.0",
+    "@tablefolk/device": "^0.1.0"
+  }
+}

package/pcm-worklet.js

@@ -0,0 +1,143 @@
+class PocketPCMProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    const opts = options.processorOptions || {};
+    this.bufferSize = opts.bufferSize || sampleRate * 60;
+    this.minBufferSamples = opts.minBufferSamples || Math.floor(sampleRate * 0.35);
+    this.targetBufferSamples = opts.targetBufferSamples || this.minBufferSamples * 2;
+    // Separate, much shorter threshold for resuming after a mid-stream
+    // underrun. minBufferSamples is a cold-start cushion (nothing has played
+    // yet, so a bigger buffer is worth the wait); once already speaking, we
+    // just want playback to pick back up as soon as anything is there rather
+    // than re-waiting for the full cold-start amount again, which turned a
+    // brief gap into a much longer audible stutter.
+    this.resumeBufferSamples = opts.resumeBufferSamples || Math.floor(sampleRate * 0.02);
+    this.ring = new Float32Array(this.bufferSize);
+    this.readPos = 0;
+    this.writePos = 0;
+    this.buffered = 0;
+    this.started = false;
+    this.everStarted = false; // false only before the very first cold start of this stream
+    this.streamEnded = false;
+    this.underruns = 0;
+    this.samplesPlayed = 0;
+    this.reportCounter = 0;
+    this.drainedReported = false;
+    this.audioPort = null;  // direct port from worker (bypasses main thread)
+    this.throttleCounter = 0;
+    // Keep-alive: instead of exact silence between lines, a faint noise
+    // (about -80 dB, far below hearing). Chrome closes its audio stream when
+    // the output is all zeros, PipeWire then suspends the speaker and the codec
+    // powers down, and waking them swallowed the first part of the next line
+    // (heard on a laptop's built-in speakers, 2026-11-07).
+    this.keepAlive = opts.keepAlive !== false;
+    this.seed = 22222;
+
+    this.port.onmessage = (e) => {
+      const m = e.data || {};
+      if (m.type === 'set_audio_port' && e.ports && e.ports.length) {
+        this.audioPort = e.ports[0];
+        this.audioPort.onmessage = (ev) => {
+          const d = ev.data || {};
+          if (d.type === 'audio') this.push(d.data);
+          else if (d.type === 'reset') this.reset();
+          else if (d.type === 'stream-ended') this.streamEnded = true;
+          else if (d.type === 'set-min-buffer') this.minBufferSamples = d.samples | 0;
+        };
+      }
+      if (m.type === 'audio') this.push(m.data);
+      else if (m.type === 'reset') this.reset();
+      else if (m.type === 'stream-ended') this.streamEnded = true;
+      else if (m.type === 'set-min-buffer') this.minBufferSamples = m.samples | 0;
+      else if (m.type === 'keep-alive') this.keepAlive = !!m.on;
+    };
+  }
+
+  // the keep-alive floor: tiny white noise
+  floor() { if (!this.keepAlive) return 0; this.seed = (this.seed * 1103515245 + 12345) & 0x7fffffff; return (this.seed / 0x7fffffff - .5) * 2e-4; }
+
+  reset() {
+    this.readPos = 0;
+    this.writePos = 0;
+    this.buffered = 0;
+    this.started = false;
+    this.everStarted = false;
+    this.streamEnded = false;
+    this.underruns = 0;
+    this.samplesPlayed = 0;
+    this.drainedReported = false;
+  }
+
+  push(data) {
+    const src = data instanceof Float32Array ? data : new Float32Array(data);
+    for (let i = 0; i < src.length; i++) {
+      if (this.buffered >= this.bufferSize) {
+        this.readPos = (this.readPos + 1) % this.bufferSize;
+        this.buffered--;
+      }
+      this.ring[this.writePos] = src[i];
+      this.writePos = (this.writePos + 1) % this.bufferSize;
+      this.buffered++;
+    }
+  }
+
+  process(inputs, outputs) {
+    const out = outputs[0][0];
+    if (!out) return true;
+
+    if (this.streamEnded && this.buffered === 0 && !this.drainedReported) {
+      this.drainedReported = true;
+      this.port.postMessage({ type: 'drained', samplesPlayed: this.samplesPlayed });
+    }
+
+    if (!this.started) {
+      const threshold = this.everStarted ? this.resumeBufferSamples : this.minBufferSamples;
+      if (this.buffered >= threshold || (this.streamEnded && this.buffered > 0)) {
+        this.port.postMessage({ type: 'playback-started', buffered: this.buffered, resumed: this.everStarted });
+        this.started = true;
+        this.everStarted = true;
+      } else {
+        for (let i = 0; i < out.length; i++) out[i] = this.floor();
+        this.report();
+        return true;
+      }
+    }
+
+    for (let i = 0; i < out.length; i++) {
+      if (this.buffered > 0) {
+        out[i] = this.ring[this.readPos];
+        this.readPos = (this.readPos + 1) % this.bufferSize;
+        this.buffered--;
+        this.samplesPlayed++;
+      } else {
+        out[i] = this.floor();
+        if (!this.streamEnded) this.underruns++;
+        this.started = false;
+      }
+    }
+
+    this.report();
+
+    // Send capacity back through the direct port if available, so the worker
+    // can throttle if needed without involving the main thread.
+    if (this.audioPort && this.buffered < this.targetBufferSamples) {
+      this.audioPort.postMessage({ type: 'capacity', buffered: this.buffered });
+    }
+    return true;
+  }
+
+  report() {
+    this.reportCounter++;
+    if (this.reportCounter % 64 === 0) {
+      this.port.postMessage({
+        type: 'stats',
+        buffered: this.buffered,
+        bufferedMs: Math.round(this.buffered / sampleRate * 1000),
+        underruns: this.underruns,
+        samplesPlayed: this.samplesPlayed,
+      });
+    }
+  }
+}
+
+registerProcessor('pocket-pcm-processor', PocketPCMProcessor);