@olares/lares-core 0.15.7 → 0.15.10

package/voice/host/install-host.sh

@@ -0,0 +1,102 @@
+#!/bin/sh
+# Install the host Bluetooth audio pieces Lares talks to. A machine without
+# Bluetooth still has to boot Lares, so every step here is allowed to fail.
+set -u
+
+VOICE_DIR=${LARES_HOST_VOICE_DIR:-}
+PROC=/host-proc/1/ns
+# The app runs this overlay when hot reload is on. Install that copy, or a
+# reboot puts the image's agent back beside a newer app.
+IMAGE_SCRIPT=/app/packages/core/voice/host/bluetooth-ready.py
+OVERLAY_SCRIPT=/devsrc/packages/core/voice/host/bluetooth-ready.py
+SCRIPT=$IMAGE_SCRIPT
+if [ -f /devsrc/.hotreload ] && [ -f /app/.lares-image-id ] && [ -f /devsrc/.lares-seeded-image-id ] \
+  && [ "$(cat /app/.lares-image-id)" = "$(cat /devsrc/.lares-seeded-image-id)" ] \
+  && [ -f "$OVERLAY_SCRIPT" ]; then
+  SCRIPT=$OVERLAY_SCRIPT
+fi
+
+if [ -z "$VOICE_DIR" ] || ! command -v nsenter >/dev/null 2>&1 || [ ! -e "$PROC/mnt" ] || [ ! -f "$SCRIPT" ]; then
+  echo "bluetooth host setup skipped: cannot enter the host" >&2
+  exit 0
+fi
+
+enter() {
+  nsenter --mount="$PROC/mnt" --net="$PROC/net" -- "$@"
+}
+
+if ! enter /bin/true; then
+  echo "bluetooth host setup skipped: host namespace refused" >&2
+  exit 0
+fi
+
+enter /bin/sh -c '
+  missing=""
+  command -v python3 >/dev/null 2>&1 || missing="$missing python3"
+  command -v bluetoothctl >/dev/null 2>&1 || missing="$missing bluez"
+  dpkg -s libspa-0.2-bluetooth >/dev/null 2>&1 || missing="$missing libspa-0.2-bluetooth"
+  if [ -z "$missing" ]; then
+    exit 0
+  fi
+  export DEBIAN_FRONTEND=noninteractive
+  if apt-get update -qq && apt-get install -y --no-install-recommends $missing; then
+    echo "$missing" | grep -q libspa-0.2-bluetooth && touch /run/lares-bluetooth-plugin-new
+  else
+    echo "bluetooth host packages failed:$missing" >&2
+  fi
+'
+
+enter /usr/bin/tee /usr/local/sbin/bluetooth-voice-ready >/dev/null < "$SCRIPT"
+enter /bin/chmod 755 /usr/local/sbin/bluetooth-voice-ready
+
+enter /usr/bin/tee /etc/systemd/system/bluetooth-wideband-speech.service >/dev/null <<'EOF'
+[Unit]
+Description=Enable Bluetooth wideband speech for HFP
+After=bluetooth.service
+PartOf=bluetooth.service
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/bluetooth-voice-ready wideband
+RemainAfterExit=yes
+
+[Install]
+WantedBy=bluetooth.service
+EOF
+
+enter /usr/bin/tee /etc/systemd/system/bluetooth-voice-ready.service >/dev/null <<EOF
+[Unit]
+Description=Lares Bluetooth voice agent
+After=bluetooth.service bluetooth-wideband-speech.service
+
+[Service]
+Type=simple
+Environment=LARES_VOICE_BLUETOOTH_DIR=${VOICE_DIR}
+ExecStart=/usr/local/sbin/bluetooth-voice-ready serve
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+enter /bin/sh -c '
+  mkdir -p "$LARES_HOST_VOICE_DIR"
+  chmod 777 "$LARES_HOST_VOICE_DIR"
+  # A drop-in here keeps running after this unit file is rewritten.
+  rm -rf /etc/systemd/system/bluetooth-voice-ready.service.d
+  rm -f /usr/local/sbin/bluetooth-voice-ready-keep
+  systemctl daemon-reload
+  systemctl enable bluetooth-wideband-speech.service bluetooth-voice-ready.service
+  systemctl restart bluetooth-wideband-speech.service || true
+  systemctl restart bluetooth-voice-ready.service || true
+  if [ -f /run/lares-bluetooth-plugin-new ] && id olares >/dev/null 2>&1; then
+    rm -f /run/lares-bluetooth-plugin-new
+    uid=$(id -u olares)
+    if [ -d "/run/user/$uid" ]; then
+      runuser -u olares -- env XDG_RUNTIME_DIR="/run/user/$uid" systemctl --user restart wireplumber || true
+    fi
+  fi
+'
+
+exit 0

package/voice/input.js

@@ -0,0 +1,4 @@
+/** Where a take is recorded. The desktop page uses the headset; the phone page uses its own mic. */
+export function captureSource(surface) {
+  return surface === "mobile" ? "device" : "headset";
+}

package/voice/install.js

@@ -0,0 +1,146 @@
+import { spawn } from "node:child_process";
+import { VoiceError } from "../router/stt.js";
+
+/** Charts the voice panel installs, stops, and resumes through olares-cli market. */
+export const VOICE_CHARTS = {
+  stt: { app: "audioqwen3asr06v3", version: "1.0.0", model: "Qwen3-ASR-0.6B" },
+  tts: { app: "audioqwen3tts06v3", version: "1.0.0", model: "Qwen3-TTS-12Hz-0.6B-CustomVoice" },
+};
+
+const OUTPUT_LIMIT = 8000;
+
+function chartFor(kind) {
+  const chart = VOICE_CHARTS[kind];
+  if (!chart) throw new VoiceError("voice_config_invalid", 400, "unknown voice chart");
+  return chart;
+}
+
+/**
+ * Market row → what the install button should do next.
+ * `running` (and a stop that did not release the app) offers 停用.
+ * `stopped` offers 启用. Anything still in flight stays on 安装中.
+ * @param {Record<string, unknown> | null | undefined} row
+ */
+export function chartPhase(row) {
+  if (!row || typeof row !== "object") return "absent";
+  const state = typeof row.state === "string" ? row.state : "";
+  if (!state || state === "uninstalled") return "absent";
+  if (state === "running" || state === "stopFailed") return "running";
+  if (state === "stopped") return "stopped";
+  if (state.endsWith("Failed") || state.endsWith("Canceled")) return "failed";
+  return "busy";
+}
+
+/** Model id Router registered for this chart, if the catalog has one. */
+export function chartModelId(kind, ids) {
+  const chart = VOICE_CHARTS[kind];
+  if (!chart) return null;
+  const list = (Array.isArray(ids) ? ids : []).map((id) => String(id ?? ""));
+  return list.find((id) => id === chart.app || id.startsWith(`${chart.app}/`) || id.includes(chart.model)) ?? null;
+}
+
+function describe(chart, row) {
+  return {
+    app: chart.app,
+    phase: chartPhase(row),
+    state: typeof row?.state === "string" ? row.state : "",
+  };
+}
+
+function runMarket(args, spawnFn) {
+  return new Promise((resolve, reject) => {
+    const child = spawnFn("olares-cli", args, {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    const take = (bucket) => (chunk) => {
+      if (bucket === "stdout") stdout = `${stdout}${chunk}`.slice(-OUTPUT_LIMIT);
+      else stderr = `${stderr}${chunk}`.slice(-OUTPUT_LIMIT);
+    };
+    child.stdout?.on("data", take("stdout"));
+    child.stderr?.on("data", take("stderr"));
+    child.on("error", (error) => {
+      reject(new VoiceError("voice_install_failed", 502, error.message));
+    });
+    child.on("close", (code) => {
+      let json = null;
+      try {
+        json = JSON.parse(stdout);
+      } catch {
+        json = null;
+      }
+      const text = `${stdout}\n${stderr}`;
+      const message = (json && typeof json.message === "string" && json.message.trim())
+        || stderr.trim()
+        || stdout.trim()
+        || `olares-cli exited ${code}`;
+      resolve({ code: code ?? 1, json, text, message });
+    });
+  });
+}
+
+function accepted(result) {
+  if (/already installed/i.test(result.text)) return true;
+  if (result.code !== 0) return false;
+  return result.json?.status !== "failed";
+}
+
+/**
+ * Install from the profile's market catalog. Returns once Market accepts;
+ * weight download continues, and status then reports `busy` until `running`.
+ * @param {"stt" | "tts"} kind
+ * @param {{ spawnFn?: typeof spawn }} [options]
+ */
+export async function installVoiceChart(kind, options = {}) {
+  const chart = chartFor(kind);
+  const spawnFn = options.spawnFn ?? spawn;
+  const result = await runMarket(
+    ["market", "install", chart.app, "-s", "market.test", "--version", chart.version, "--compute-mode", "nvidia", "-o", "json"],
+    spawnFn,
+  );
+  if (!accepted(result)) {
+    throw new VoiceError("voice_install_failed", 502, result.message);
+  }
+  return { app: chart.app, version: chart.version };
+}
+
+/** @param {"stt" | "tts"} kind */
+export async function voiceChartStatus(kind, options = {}) {
+  const chart = chartFor(kind);
+  const result = await runMarket(
+    ["market", "status", chart.app, "-a", "-o", "json"],
+    options.spawnFn ?? spawn,
+  );
+  if (!result.json) throw new VoiceError("voice_install_failed", 502, result.message);
+  return describe(chart, result.json);
+}
+
+export async function voiceChartsStatus(options = {}) {
+  const [stt, tts] = await Promise.all([
+    voiceChartStatus("stt", options),
+    voiceChartStatus("tts", options),
+  ]);
+  return { stt, tts };
+}
+
+async function settle(kind, verb, code, options) {
+  const chart = chartFor(kind);
+  const result = await runMarket(
+    ["market", verb, chart.app, "--watch", "-o", "json"],
+    options.spawnFn ?? spawn,
+  );
+  if (!accepted(result)) throw new VoiceError(code, 502, result.message);
+  return voiceChartStatus(kind, options);
+}
+
+/** Stop the chart and let Market release its memory and GPU. */
+export function stopVoiceChart(kind, options = {}) {
+  return settle(kind, "stop", "voice_stop_failed", options);
+}
+
+/** Start a stopped chart again. */
+export function resumeVoiceChart(kind, options = {}) {
+  return settle(kind, "resume", "voice_resume_failed", options);
+}

package/voice/languages.js

@@ -14,7 +14,17 @@ export function voiceValueFromMenu(id) {
   return id === VOICE_AUTO ? "" : id;
 }
 
-export const EMPTY_VOICE_CONFIG = { model: "", language: "" };
+export const EMPTY_VOICE_CONFIG = { model: "", ttsModel: "", language: "", speak: false };
+
+export function voiceChoiceItems(ids) {
+  return ids.map((id) => ({ id, label: id }));
+}
+
+/** Stored choice when it is still listed, otherwise the first available model. */
+export function selectedVoice(stored, ids) {
+  if (stored && ids.includes(stored)) return stored;
+  return ids[0] ?? "";
+}
 
 export function voiceLanguageItems(autoLabel) {
   return [{ id: VOICE_AUTO, label: autoLabel }, ...STT_LANGUAGE_CHOICES];

package/voice/link.js

@@ -0,0 +1,86 @@
+import { VoiceError } from "../router/stt.js";
+import { askAgent, liveAgent } from "./agent.js";
+
+const SCAN_WAIT_MS = 45_000;
+const CONNECT_WAIT_MS = 90_000;
+const ADDRESS = /^[0-9A-F]{2}(?::[0-9A-F]{2}){5}$/;
+
+export function normalizeBluetoothAddress(value) {
+  const address = String(value ?? "").trim().toUpperCase();
+  if (!ADDRESS.test(address)) {
+    throw new VoiceError("voice_bluetooth_invalid", 400, "invalid bluetooth address");
+  }
+  return address;
+}
+
+export function normalizeBluetoothDevices(raw) {
+  if (!Array.isArray(raw)) return [];
+  const devices = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const address = String(item.address ?? "").trim().toUpperCase();
+    if (!ADDRESS.test(address)) continue;
+    const name = String(item.name ?? "").replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 80);
+    devices.push({
+      address,
+      name: name || address,
+      paired: item.paired === true,
+      connected: item.connected === true,
+    });
+  }
+  return devices;
+}
+
+/** Bring the headset up. No agent means this machine has nothing to prepare. */
+export async function ensureBluetoothReady(options = {}) {
+  if (!await liveAgent(options)) return { ready: true, skipped: true };
+  const result = await askAgent("ensure", {}, options);
+  if (result.ready) return result;
+  throw new VoiceError("voice_bluetooth_not_ready", 503, result.error || "bluetooth headset is not capturing");
+}
+
+/** Devices advertising during this scan, including ones already connected. */
+export async function scanBluetoothDevices(options = {}) {
+  const result = await askAgent("scan", {}, { ...options, timeoutMs: options.timeoutMs ?? SCAN_WAIT_MS });
+  if (result.op !== "scan") {
+    throw new VoiceError("voice_bluetooth_unavailable", 503, "bluetooth agent does not support scanning");
+  }
+  if (result.error) {
+    const code = result.code === "voice_bluetooth_unavailable"
+      ? "voice_bluetooth_unavailable"
+      : "voice_bluetooth_scan_failed";
+    throw new VoiceError(code, code === "voice_bluetooth_unavailable" ? 503 : 502, String(result.error));
+  }
+  return { devices: normalizeBluetoothDevices(result.devices) };
+}
+
+export async function connectBluetoothDevice(address, options = {}) {
+  const mac = normalizeBluetoothAddress(address);
+  const result = await askAgent("connect", { address: mac }, {
+    ...options,
+    timeoutMs: options.timeoutMs ?? CONNECT_WAIT_MS,
+  });
+  if (result.op !== "connect") {
+    throw new VoiceError("voice_bluetooth_unavailable", 503, "bluetooth agent does not support connecting");
+  }
+  if (!result.connected) {
+    const code = result.code === "voice_bluetooth_unavailable"
+      ? "voice_bluetooth_unavailable"
+      : "voice_bluetooth_connect_failed";
+    throw new VoiceError(code, code === "voice_bluetooth_unavailable" ? 503 : 502, result.error || "bluetooth connect failed");
+  }
+  const [device] = normalizeBluetoothDevices([{
+    address: result.address || mac,
+    name: result.name,
+    paired: true,
+    connected: true,
+  }]);
+  return device ?? { address: mac, name: mac, paired: true, connected: true };
+}
+
+export async function bluetoothRequest(body, options) {
+  const op = body && typeof body === "object" ? body.op : "";
+  if (op === "scan") return scanBluetoothDevices(options);
+  if (op === "connect") return connectBluetoothDevice(body.address, options);
+  throw new VoiceError("voice_bluetooth_invalid", 400, "unknown bluetooth operation");
+}

package/voice/pcm.js

@@ -0,0 +1,100 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VoiceError } from "../router/stt.js";
+
+/** Parakeet transcribes 16 kHz mono PCM. 48 kHz browser captures come back as a short wrong word. */
+export const STT_SAMPLE_RATE = 16_000;
+const PREPARE_TIMEOUT_MS = 30_000;
+
+const INPUT_EXT = {
+  "audio/webm": "webm",
+  "audio/ogg": "ogg",
+  "audio/mp4": "m4a",
+  "audio/mpeg": "mp3",
+  "audio/aac": "aac",
+  "audio/wav": "wav",
+  "audio/wave": "wav",
+  "audio/x-wav": "wav",
+};
+
+export function sttInputExtension(contentType) {
+  const base = String(contentType ?? "").split(";", 1)[0].trim().toLowerCase();
+  return INPUT_EXT[base] ?? "bin";
+}
+
+export function sttPcmArgs(inputPath, outputPath) {
+  return [
+    "-hide_banner",
+    "-loglevel", "error",
+    "-y",
+    "-i", inputPath,
+    "-ac", "1",
+    "-ar", String(STT_SAMPLE_RATE),
+    "-c:a", "pcm_s16le",
+    "-f", "wav",
+    outputPath,
+  ];
+}
+
+function assertSttWav(wav) {
+  if (wav.length < 44 || wav.toString("ascii", 0, 4) !== "RIFF" || wav.toString("ascii", 8, 12) !== "WAVE") {
+    throw new VoiceError("voice_audio_unreadable", 400, "audio could not be prepared");
+  }
+  if (wav.readUInt16LE(20) !== 1 || wav.readUInt16LE(22) !== 1 || wav.readUInt32LE(24) !== STT_SAMPLE_RATE || wav.readUInt16LE(34) !== 16) {
+    throw new VoiceError("voice_audio_unreadable", 400, "audio could not be prepared");
+  }
+}
+
+function runFfmpeg(ffmpegBin, args, spawnFn) {
+  return new Promise((resolve, reject) => {
+    const child = spawnFn(ffmpegBin, args, { stdio: ["ignore", "ignore", "pipe"] });
+    const errors = [];
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+    }, PREPARE_TIMEOUT_MS);
+    child.stderr?.on("data", (chunk) => {
+      errors.push(chunk);
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      const detail = Buffer.concat(errors).toString("utf8").trim().slice(-300);
+      reject(new Error(detail || `ffmpeg exited ${code}`));
+    });
+  });
+}
+
+/**
+ * Decode whatever the browser recorded into the one PCM layout the speech model accepts.
+ * @param {Buffer} bytes
+ * @param {string} [contentType]
+ * @param {{ spawnFn?: typeof spawn, ffmpegBin?: string }} [options]
+ * @returns {Promise<Buffer>}
+ */
+export async function normalizeSttPcm(bytes, contentType, options = {}) {
+  const dir = await mkdtemp(join(tmpdir(), "lares-stt-"));
+  const inputPath = join(dir, `in.${sttInputExtension(contentType)}`);
+  const outputPath = join(dir, "out.wav");
+  try {
+    await writeFile(inputPath, bytes);
+    await runFfmpeg(options.ffmpegBin ?? "ffmpeg", sttPcmArgs(inputPath, outputPath), options.spawnFn ?? spawn);
+    const wav = await readFile(outputPath);
+    assertSttWav(wav);
+    return wav;
+  } catch (err) {
+    if (err instanceof VoiceError) throw err;
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new VoiceError("voice_audio_unreadable", 400, detail || "audio could not be prepared");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}

package/voice/playback.js

@@ -0,0 +1,7 @@
+/**
+ * The phone plays the same answer the headset plays.
+ * The desktop page shares the room with that headset, and its browser does not open the call link.
+ */
+export function browserPlays(surface, bluetooth) {
+  return !(surface === "pc" && bluetooth === "played");
+}

package/voice/problem.js

@@ -0,0 +1,46 @@
+/**
+ * What to tell the user when answer playback cannot happen.
+ * Recognized codes stay in the product language. A generic failure keeps the
+ * server's own detail so the notice says what actually broke.
+ */
+
+const REPLACED = {
+  voice_model_unavailable: "voice_tts_unavailable",
+  voice_timeout: "voice_speak_timeout",
+  voice_failed: "voice_speak_failed",
+};
+
+const WITH_DETAIL = new Set(["voice_speak_failed", "voice_speak_timeout"]);
+const STOCK = new Set([
+  "speech timed out",
+  "no speech model available",
+  "speech playback is off",
+  "nothing to speak",
+]);
+
+export function speakToggleNotice(ttsModels) {
+  return Array.isArray(ttsModels) && ttsModels.length === 0 ? "voice_tts_unavailable" : "";
+}
+
+function translated(translate, code) {
+  if (!code) return "";
+  const key = `error.${code}`;
+  const text = translate(key);
+  return text === key ? "" : text;
+}
+
+export function speakProblemText(translate, err) {
+  const code = err && typeof err === "object" && typeof err.code === "string" ? err.code : "";
+  const raw = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  const message = raw && raw !== code && !STOCK.has(raw) ? raw : "";
+  const mapped = REPLACED[code] || (code.startsWith("voice_") ? code : "");
+  const text = translated(translate, mapped);
+  if (text && message && WITH_DETAIL.has(mapped)) return `${text}: ${message}`;
+  if (text) return text;
+  if (!code && message.startsWith("voice_")) {
+    const fromMessage = translated(translate, REPLACED[message] || message);
+    if (fromMessage) return fromMessage;
+  }
+  if (message) return message;
+  return translated(translate, "voice_speak_failed") || "voice_speak_failed";
+}

package/voice/recorder.js

@@ -16,14 +16,89 @@ export const RECORDING_AUDIO = {
   autoGainControl: true,
 };
 
-export function isComposerVoiceReady(phase, setDraft) {
-  return phase === "plain" && typeof setDraft === "function";
-}
-
 export function isRecordingTooShort(durationMs, byteSize) {
   return durationMs < MIN_RECORDING_MS || byteSize < MIN_RECORDING_BYTES;
 }
 
+/** Chrome's "Default" input is not the Pulse default. Match the headset the host just armed. */
+export function pickInputDevice(devices, label) {
+  const wanted = String(label ?? "").trim();
+  if (!wanted) return "";
+  const match = (devices ?? []).find((device) => (
+    device?.kind === "audioinput"
+    && device.deviceId
+    && device.deviceId !== "default"
+    && device.label === wanted
+  ));
+  return match?.deviceId ?? "";
+}
+
+async function deviceIdForLabel(mediaDevices, label) {
+  const listed = async () => pickInputDevice(await mediaDevices.enumerateDevices(), label);
+  const found = await listed();
+  if (found) return found;
+  const devices = await mediaDevices.enumerateDevices();
+  if (devices.some((device) => device?.kind === "audioinput" && device.label)) return "";
+  const probe = await mediaDevices.getUserMedia({ audio: true });
+  probe.getTracks().forEach((track) => track.stop());
+  return listed();
+}
+
+/**
+ * Open the headset Chrome lists under `ready.label`.
+ * Without a label there is no headset to aim at, so the browser default is used.
+ */
+export async function openRecordingStream(ready, mediaDevices = globalThis.navigator?.mediaDevices) {
+  const label = String(ready?.label ?? "").trim();
+  const audio = { ...RECORDING_AUDIO };
+  if (label) {
+    const deviceId = await deviceIdForLabel(mediaDevices, label);
+    if (!deviceId) throw new Error("voice_bluetooth_not_ready");
+    audio.deviceId = { exact: deviceId };
+  }
+  return mediaDevices.getUserMedia({ audio });
+}
+
+export function frameHasAudio(samples) {
+  for (let i = 0; i < samples.length; i += 1) {
+    if (samples[i] !== 0) return true;
+  }
+  return false;
+}
+
+/**
+ * The headset link stays at digital silence for a couple of seconds after it opens.
+ * Speech spoken into that hole never reaches the recognizer.
+ */
+export function waitUntilAudible(stream, timeoutMs = 4000) {
+  const AudioCtx = globalThis.AudioContext || globalThis.webkitAudioContext;
+  if (!AudioCtx) return Promise.resolve(false);
+  const ctx = new AudioCtx();
+  const source = ctx.createMediaStreamSource(stream);
+  const proc = ctx.createScriptProcessor(4096, 1, 1);
+  const mute = ctx.createGain();
+  mute.gain.value = 0;
+  source.connect(proc);
+  proc.connect(mute);
+  mute.connect(ctx.destination);
+  return new Promise((resolve) => {
+    const finish = (heard) => {
+      proc.onaudioprocess = null;
+      proc.disconnect();
+      source.disconnect();
+      mute.disconnect();
+      void ctx.close?.();
+      resolve(heard);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    proc.onaudioprocess = (event) => {
+      if (!frameHasAudio(event.inputBuffer.getChannelData(0))) return;
+      clearTimeout(timer);
+      finish(true);
+    };
+  });
+}
+
 export function pickRecordingMime(recorder = globalThis.MediaRecorder) {
   if (typeof recorder === "undefined" || recorder === undefined) return "";
   for (const type of MIME_CANDIDATES) {

package/voice/script.js

@@ -0,0 +1,35 @@
+import { segment } from "sentencex";
+
+/**
+ * Kokoro's pipeline splits on newlines and stitches the audio with no gap, and
+ * it does not treat punctuation as a pause. Sentence boundaries come from
+ * Wikimedia sentencex (English abbreviations, decimals, ellipsis). The gap
+ * matches Kokoro-FastAPI's sentence padding: 150ms, doubled for . ! ?
+ */
+export const SENTENCE_GAP_MS = 300;
+
+function plain(text) {
+  return String(text ?? "")
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/!\[[^\]]*]\([^)]*\)/g, " ")
+    .replace(/\[([^\]]+)]\([^)]*\)/g, "$1")
+    .replace(/[#>*_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 2000);
+}
+
+export function speechSegments(text) {
+  const source = plain(text);
+  if (!source) return [];
+  const sentences = segment("en", source).map((part) => part.trim()).filter(Boolean);
+  return sentences.map((sentence, index) => ({
+    text: sentence,
+    gapMs: index === sentences.length - 1 ? 0 : SENTENCE_GAP_MS,
+  }));
+}
+
+export function speechScript(text) {
+  return speechSegments(text).map((part) => part.text).join("\n");
+}