mac-voice-mcp 0.3.1 → 0.4.0

package/dist/kokoro-text.js

@@ -0,0 +1,105 @@
+/**
+ * Text preparation for the Kokoro voice (pure, unit-tested).
+ *
+ * Kokoro reads text through espeak-ng, which trips over some developer jargon, silently stops at
+ * newlines, and truncates anything past ~510 tokens. So before speaking we fix the known
+ * mispronunciations and cut the text into sentence-sized chunks that can be generated one at a
+ * time — the first chunk starts playing while the next is being generated.
+ */
+/** Words and patterns espeak gets wrong, with what to say instead. Applied in order. */
+export const PRONUNCIATIONS = [
+    [/\bJSON\b/g, "jay-son"],
+    [/\bYAML\b/g, "yammel"],
+    [/\bSQLite\b/gi, "S Q lite"],
+    [/\bRAM\b/g, "ram"],
+    [/\bGIFs?\b/g, (m) => (m.endsWith("s") ? "gifs" : "gif")],
+    // file.ext → "file dot ext", spelling short extensions: index.ts → "index dot T S"
+    [/\b([A-Za-z][\w-]*)\.(ts|js|tsx|jsx|py|rb|go|rs|md|sh|css|html|json|yml|yaml|toml)\b/g, "$1 dot $2"],
+    // version numbers: 1.2.3 → "1 point 2 point 3" (espeak reads them as decimals)
+    [/\bv?(\d+)\.(\d+)\.(\d+)\b/g, "$1 point $2 point $3"],
+];
+const SPELL_OUT = new Set(["ts", "js", "tsx", "jsx", "py", "rb", "rs", "md", "sh", "css", "yml"]);
+const SAY_AS = { json: "jay-son", yaml: "yammel" };
+export function fixPronunciation(text) {
+    let out = text;
+    for (const [pattern, replacement] of PRONUNCIATIONS)
+        out = out.replace(pattern, replacement);
+    // file extensions: spell the short ones letter by letter ("dot ts" → "dot T S")
+    return out.replace(/\bdot (\w+)\b/g, (m, ext) => {
+        const lower = ext.toLowerCase();
+        if (SAY_AS[lower])
+            return `dot ${SAY_AS[lower]}`;
+        return SPELL_OUT.has(lower) ? `dot ${ext.toUpperCase().split("").join(" ")}` : m;
+    });
+}
+/** Longest chunk handed to Kokoro at once, in characters (well under its ~510-token limit). */
+export const MAX_CHUNK_CHARS = 250;
+/**
+ * The first chunk is kept short: nothing plays until it's generated, so its length is the delay
+ * before the first sound. Later chunks are generated while earlier ones play.
+ */
+export const FIRST_CHUNK_CHARS = 100;
+/** Short sentences are merged up to this size: very short inputs sound worse. */
+const MERGE_UP_TO = 120;
+/** The first chunk only absorbs the next sentence while it's this short (e.g. "Done."). */
+const FIRST_MERGE_UP_TO = 30;
+/** Cut one sentence into pieces of at most `limit` characters: at clause boundaries, else between words. */
+function splitLong(sentence, limit) {
+    const pieces = [];
+    let current = "";
+    for (const clause of sentence.split(/(?<=[,;:—–])\s+/)) {
+        for (const word of clause.split(" ")) {
+            if (current && current.length + 1 + word.length > limit) {
+                pieces.push(current);
+                current = "";
+            }
+            current = current ? `${current} ${word}` : word;
+        }
+        if (current.length >= limit * 0.6) {
+            pieces.push(current);
+            current = "";
+        }
+    }
+    if (current)
+        pieces.push(current);
+    return pieces;
+}
+/**
+ * Split text into speakable chunks: sentences, merged when short, split at commas/words when long.
+ * The first chunk is short, so speech starts quickly.
+ */
+export function chunkForSpeech(text, maxChars = MAX_CHUNK_CHARS) {
+    const clean = text
+        .replace(/\s*\n+\s*/g, ". ") // Kokoro stops at a newline
+        .replace(/([.!?:;,])\s*\.(?=\s|$)/g, "$1") // "Done:\n" → "Done:" not "Done:."
+        .replace(/\.(\s*\.)+/g, ".")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!/[\p{L}\p{N}]/u.test(clean))
+        return []; // nothing to say (blank, or only punctuation)
+    const sentences = clean.match(/[^.!?]+(?:[.!?]+(?=\s|$)|$)/g)?.map((s) => s.trim()).filter(Boolean) ?? [clean];
+    const pieces = [];
+    for (const sentence of sentences) {
+        const limit = pieces.length === 0 ? Math.min(FIRST_CHUNK_CHARS, maxChars) : maxChars;
+        if (sentence.length <= limit)
+            pieces.push(sentence);
+        else
+            pieces.push(...splitLong(sentence, limit));
+    }
+    // Merge neighbours while short, so tiny fragments don't get their own odd-sounding chunk.
+    const chunks = [];
+    for (const p of pieces) {
+        const last = chunks[chunks.length - 1];
+        const mergeUpTo = chunks.length === 1 ? FIRST_MERGE_UP_TO : MERGE_UP_TO;
+        const limit = chunks.length === 1 ? FIRST_CHUNK_CHARS : maxChars;
+        if (last !== undefined && last.length < mergeUpTo && last.length + 1 + p.length <= limit)
+            chunks[chunks.length - 1] = `${last} ${p}`;
+        else
+            chunks.push(p);
+    }
+    return chunks;
+}
+/** The text Kokoro should speak, as chunks. */
+export function prepareForKokoro(text) {
+    return chunkForSpeech(fixPronunciation(text));
+}

package/dist/kokoro-worker.js

@@ -0,0 +1,103 @@
+/**
+ * The Kokoro voice, in its own process.
+ *
+ * Kokoro (kokoro-js + onnxruntime) is a ~330 MB model that takes seconds to load and holds
+ * hundreds of MB of memory, so it runs here, kept warm between turns, instead of inside the MCP
+ * server. If it crashes or leaks, the server just starts a fresh one.
+ *
+ * Protocol: one JSON object per line.
+ *   in  (stdin): {type:"speak", id, chunks:[text…]}  {type:"cancel", id}
+ *   out (fd 3):  {type:"ready", voice, voices, loadMs}
+ *                {type:"audio", id, seq, pcm}      pcm = base64 16-bit little-endian, 24 kHz mono
+ *                {type:"done", id, cancelled, rssMb}
+ *                {type:"error", id?, message, fatal?}
+ * stdout is not used for messages: libraries print to it (e.g. a voice table), so it's left to logs.
+ *
+ * Settings come from the environment (set by kokoro.ts): KOKORO_DIR, KOKORO_DTYPE, KOKORO_VOICE,
+ * KOKORO_SPEED, KOKORO_ALLOW_DOWNLOAD ("1" only during an install the user agreed to).
+ */
+import { createWriteStream } from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import { floatToPcm16 } from "./pcm.js";
+const KOKORO_MODEL_ID = "onnx-community/Kokoro-82M-v1.0-ONNX";
+const out = createWriteStream("", { fd: 3 });
+out.on("error", () => process.exit(0)); // the server went away
+const send = (msg) => out.write(JSON.stringify(msg) + "\n");
+async function main() {
+    const dir = process.env.KOKORO_DIR;
+    if (!dir)
+        throw new Error("KOKORO_DIR is not set");
+    const dtype = process.env.KOKORO_DTYPE === "q8" ? "q8" : "fp32";
+    const speed = Number(process.env.KOKORO_SPEED) > 0 ? Number(process.env.KOKORO_SPEED) : 1;
+    const t0 = Date.now();
+    // entry.mjs re-exports KokoroTTS and transformers' env from the same install, so they share state.
+    const mod = (await import(pathToFileURL(path.join(dir, "entry.mjs")).href));
+    mod.env.cacheDir = path.join(dir, "models");
+    mod.env.allowRemoteModels = process.env.KOKORO_ALLOW_DOWNLOAD === "1";
+    let lastProgress = -1;
+    const tts = await mod.KokoroTTS.from_pretrained(KOKORO_MODEL_ID, {
+        dtype,
+        device: "cpu",
+        progress_callback: (p) => {
+            if (p.status !== "progress" || !p.file?.endsWith(".onnx"))
+                return;
+            const pct = Math.floor((p.progress ?? 0) / 10) * 10;
+            if (pct !== lastProgress) {
+                lastProgress = pct;
+                send({ type: "progress", message: `downloading the Kokoro model: ${pct}%` });
+            }
+        },
+    });
+    const voices = Object.keys(tts.voices);
+    const wanted = process.env.KOKORO_VOICE || "af_heart";
+    const voice = voices.includes(wanted) ? wanted : "af_heart";
+    if (voice !== wanted)
+        console.error(`[kokoro] unknown voice "${wanted}", using af_heart`);
+    send({ type: "ready", voice, voices, loadMs: Date.now() - t0 });
+    // One request at a time; a cancel flips its flag and the loop stops at the next chunk.
+    const cancelled = new Set();
+    let queue = Promise.resolve();
+    const speakRequest = async (id, chunks) => {
+        for (let seq = 0; seq < chunks.length; seq++) {
+            // Generating blocks this process's event loop, so let it read stdin (a cancel) between chunks.
+            await new Promise((r) => setImmediate(r));
+            if (cancelled.has(id))
+                break;
+            const audio = await tts.generate(chunks[seq], { voice, speed });
+            if (cancelled.has(id))
+                break;
+            send({ type: "audio", id, seq, pcm: floatToPcm16(audio.audio).toString("base64") });
+        }
+        send({ type: "done", id, cancelled: cancelled.delete(id), rssMb: Math.round(process.memoryUsage().rss / 1e6) });
+    };
+    const lines = createInterface({ input: process.stdin });
+    lines.on("line", (line) => {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const id = String(msg.id ?? "");
+        if (msg.type === "cancel")
+            cancelled.add(id);
+        else if (msg.type === "speak" && Array.isArray(msg.chunks)) {
+            const chunks = msg.chunks.map(String);
+            queue = queue
+                .then(() => speakRequest(id, chunks))
+                .catch((e) => {
+                cancelled.delete(id);
+                send({ type: "error", id, message: e instanceof Error ? e.message : String(e) });
+            });
+        }
+    });
+    // The server closed our stdin (it exited, or was killed): stop too, never linger.
+    lines.on("close", () => void queue.finally(() => process.exit(0)));
+}
+main().catch((e) => {
+    send({ type: "error", message: e instanceof Error ? e.message : String(e), fatal: true });
+    out.end(() => process.exit(1));
+});

package/dist/kokoro.js

@@ -0,0 +1,449 @@
+/**
+ * The optional Kokoro voice: a natural-sounding, on-device neural voice (Kokoro-82M, Apache-2.0).
+ *
+ * Off until the user installs it (voice_setup with kokoro=true): that installs kokoro-js with npm
+ * into ~/.cache/mac-voice-mcp/kokoro and downloads the model once. Nothing is bundled with this
+ * package, and nothing is ever downloaded without that consent.
+ *
+ * The model runs in a separate worker process (kokoro-worker.ts), kept warm between turns and
+ * stopped after VOICE_MCP_SERVER_IDLE_MINUTES. Text is spoken sentence by sentence: the first
+ * sentence plays while the next ones are generated, through SoX's `play` (gapless), or `afplay`.
+ *
+ * Any failure falls back to the built-in voice (see speak() in audio.ts), so a broken Kokoro
+ * install can never make the server mute.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { CONFIG, debug, IS_MAC, log } from "./config.js";
+import { prepareForKokoro } from "./kokoro-text.js";
+import { resamplePcm16, wavHeaderFor } from "./pcm.js";
+import { CancelledError, isExecutable, run, SetupError, tail, which } from "./proc.js";
+/** The kokoro-js release we install and test against. */
+export const KOKORO_JS_VERSION = "1.2.1";
+export const KOKORO_RATE = 24_000;
+/** Approximate model download sizes. */
+export const KOKORO_SIZES_MB = { fp32: 326, q8: 92 };
+/** A short pause between sentences, so they don't run into each other. */
+const GAP_MS = 120;
+/** Restart the worker once it holds this much memory (onnxruntime can grow over a long session). */
+const RECYCLE_RSS_MB = 1500;
+/** A model already on disk loads in a few seconds; allow for a slow, busy machine. */
+const LOAD_TIMEOUT_MS = 120_000;
+/** First install: the download may be slow. */
+const INSTALL_LOAD_TIMEOUT_MS = 30 * 60_000;
+const ENTRY_MJS = "// Written by mac-voice-mcp: lets its Kokoro worker load kokoro-js and share transformers' settings.\n" +
+    'export { KokoroTTS } from "kokoro-js";\n' +
+    'export { env } from "@huggingface/transformers";\n';
+export function kokoroFiles() {
+    const dir = CONFIG.kokoroDir;
+    const modelDir = path.join(dir, "models", "onnx-community", "Kokoro-82M-v1.0-ONNX", "onnx");
+    return {
+        dir,
+        entry: path.join(dir, "entry.mjs"),
+        pkg: path.join(dir, "node_modules", "kokoro-js", "package.json"),
+        model: path.join(modelDir, CONFIG.kokoroDtype === "q8" ? "model_quantized.onnx" : "model.onnx"),
+    };
+}
+/** kokoro-js is installed (the model may still be missing). */
+export function isKokoroInstalled() {
+    const f = kokoroFiles();
+    return existsSync(f.entry) && existsSync(f.pkg);
+}
+/** The model for the configured precision is on disk. */
+export function isKokoroModelPresent() {
+    return existsSync(kokoroFiles().model);
+}
+/** Speak with Kokoro? Yes when the user installed it (VOICE_MCP_TTS=auto) or asked for it (=kokoro). */
+export function kokoroEnabled() {
+    if (CONFIG.tts === "say")
+        return false;
+    if (CONFIG.tts === "kokoro")
+        return true;
+    return isKokoroInstalled() && isKokoroModelPresent();
+}
+/** Kokoro failed partway: what hadn't been spoken yet, so the built-in voice can finish it. */
+export class KokoroError extends Error {
+    unspoken;
+    name = "KokoroError";
+    constructor(message, unspoken) {
+        super(message);
+        this.unspoken = unspoken;
+    }
+}
+class KokoroWorker {
+    child = null;
+    ready = null;
+    requests = new Map();
+    idleTimer;
+    nextId = 1;
+    logTail = "";
+    info = null;
+    onProgress;
+    get running() {
+        return !!this.child && this.child.exitCode === null && this.child.signalCode === null;
+    }
+    /** Start (or reuse) the worker; resolves once the model is loaded. */
+    start(opts = {}) {
+        this.touch();
+        if (this.ready && this.running)
+            return this.ready;
+        const script = fileURLToPath(new URL("./kokoro-worker.js", import.meta.url));
+        const child = spawn(process.execPath, [script], {
+            stdio: ["pipe", "pipe", "pipe", "pipe"],
+            windowsHide: true,
+            env: {
+                ...process.env,
+                KOKORO_DIR: CONFIG.kokoroDir,
+                KOKORO_DTYPE: CONFIG.kokoroDtype,
+                KOKORO_VOICE: CONFIG.kokoroVoice,
+                KOKORO_SPEED: String(CONFIG.kokoroSpeed),
+                KOKORO_ALLOW_DOWNLOAD: opts.allowDownload ? "1" : "0",
+            },
+        });
+        this.child = child;
+        this.logTail = "";
+        debug("kokoro: starting worker");
+        const keepLog = (d) => {
+            this.logTail = (this.logTail + d).slice(-3000);
+            debug("kokoro:", d.trimEnd());
+        };
+        child.stdout.setEncoding("utf8").on("data", keepLog);
+        child.stderr.setEncoding("utf8").on("data", keepLog);
+        child.stdin.on("error", () => { });
+        this.ready = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error("the Kokoro voice took too long to load"));
+                this.stop();
+            }, opts.allowDownload ? INSTALL_LOAD_TIMEOUT_MS : LOAD_TIMEOUT_MS);
+            timer.unref();
+            createInterface({ input: child.stdio[3] }).on("line", (line) => {
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                const req = typeof msg.id === "string" ? this.requests.get(msg.id) : undefined;
+                switch (msg.type) {
+                    case "ready":
+                        clearTimeout(timer);
+                        this.info = { voice: String(msg.voice), voices: msg.voices ?? [], loadMs: Number(msg.loadMs) };
+                        debug(`kokoro: ready in ${this.info.loadMs} ms (voice ${this.info.voice})`);
+                        resolve(this.info);
+                        break;
+                    case "progress":
+                        this.onProgress?.(String(msg.message));
+                        break;
+                    case "audio":
+                        req?.onAudio(Number(msg.seq), Buffer.from(String(msg.pcm), "base64"));
+                        break;
+                    case "done":
+                        if (req && typeof msg.id === "string") {
+                            this.requests.delete(msg.id);
+                            req.resolve({ rssMb: Number(msg.rssMb), cancelled: msg.cancelled === true });
+                        }
+                        break;
+                    case "error":
+                        if (msg.fatal) {
+                            clearTimeout(timer);
+                            reject(new Error(String(msg.message)));
+                        }
+                        else if (req && typeof msg.id === "string") {
+                            this.requests.delete(msg.id);
+                            req.reject(new Error(String(msg.message)));
+                        }
+                        break;
+                }
+            });
+            child.on("error", (e) => {
+                clearTimeout(timer);
+                reject(e);
+            });
+            child.on("exit", (code, signal) => {
+                clearTimeout(timer);
+                const why = new Error(`the Kokoro worker stopped (${signal ?? `exit ${code}`})${this.logTail ? `: ${tail(this.logTail, 3)}` : ""}`);
+                reject(why); // no-op once ready
+                for (const r of this.requests.values())
+                    r.reject(why);
+                this.requests.clear();
+                if (this.child === child) {
+                    this.child = null;
+                    this.ready = null;
+                    this.info = null;
+                }
+            });
+        });
+        this.ready.catch(() => { }); // callers handle it; don't crash on an unobserved rejection
+        return this.ready;
+    }
+    /** Generate `chunks` in order; onAudio receives each chunk's 24 kHz PCM as soon as it's ready. */
+    speak(chunks, onAudio, signal) {
+        const child = this.child;
+        if (!child || !this.running)
+            return Promise.reject(new Error("the Kokoro worker is not running"));
+        const id = String(this.nextId++);
+        this.touch();
+        return new Promise((resolve, reject) => {
+            // Cancel: stop waiting right away; the worker drops the rest at its next sentence.
+            const onAbort = () => {
+                child.stdin.write(JSON.stringify({ type: "cancel", id }) + "\n");
+                const req = this.requests.get(id);
+                this.requests.delete(id);
+                req?.resolve({ rssMb: 0, cancelled: true });
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const done = () => {
+                signal?.removeEventListener("abort", onAbort);
+                this.touch();
+            };
+            if (signal?.aborted)
+                return resolve({ rssMb: 0, cancelled: true });
+            this.requests.set(id, {
+                onAudio,
+                resolve: (r) => {
+                    done();
+                    if (r.rssMb > RECYCLE_RSS_MB) {
+                        debug(`kokoro: worker uses ${r.rssMb} MB — restarting it next time`);
+                        this.stop();
+                    }
+                    resolve(r);
+                },
+                reject: (e) => {
+                    done();
+                    reject(e);
+                },
+            });
+            child.stdin.write(JSON.stringify({ type: "speak", id, chunks }) + "\n");
+        });
+    }
+    touch() {
+        clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => {
+            debug("kokoro: idle — stopping the worker to free memory");
+            this.stop();
+        }, CONFIG.serverIdleMinutes * 60_000);
+        this.idleTimer.unref();
+    }
+    stop() {
+        clearTimeout(this.idleTimer);
+        const child = this.child;
+        this.child = null;
+        this.ready = null;
+        this.info = null;
+        if (child && child.exitCode === null) {
+            child.stdin?.end(); // the worker exits when its stdin closes
+            setTimeout(() => child.exitCode === null && child.kill("SIGKILL"), 2000).unref();
+        }
+    }
+}
+const worker = new KokoroWorker();
+export function stopKokoro() {
+    worker.stop();
+}
+/** The voice actually in use, once the worker has loaded (for reports). */
+export function kokoroVoiceLabel() {
+    const voice = worker.info?.voice ?? CONFIG.kokoroVoice;
+    return `Kokoro ${voice} (${CONFIG.kokoroDtype})`;
+}
+/** SoX `play`, streaming raw PCM: gapless, and starts with the first sentence. */
+function soxPlayer(bin) {
+    const child = spawn(bin, ["-q", "-t", "raw", "-r", String(KOKORO_RATE), "-e", "signed-integer", "-b", "16", "-c", "1", "-"], {
+        stdio: ["pipe", "ignore", "pipe"],
+        windowsHide: true,
+    });
+    let stderr = "";
+    child.stderr.setEncoding("utf8").on("data", (d) => (stderr = (stderr + d).slice(-2000)));
+    child.stdin.on("error", () => { });
+    const closed = new Promise((resolve, reject) => {
+        child.on("error", reject);
+        child.on("close", resolve);
+    });
+    closed.catch(() => { });
+    return {
+        write: (pcm) => void child.stdin.write(pcm),
+        finish: async () => {
+            child.stdin.end();
+            const code = await closed;
+            if (code !== 0)
+                throw new Error(`play failed (exit ${code}): ${tail(stderr) || "no output"}`);
+        },
+        kill: () => {
+            if (child.exitCode === null)
+                child.kill("SIGKILL");
+        },
+    };
+}
+/** macOS without SoX: one short WAV per sentence through afplay, back to back. */
+function afplayPlayer() {
+    let dir;
+    let queue = Promise.resolve();
+    let current = null;
+    let killed = false;
+    let n = 0;
+    const playOne = async (pcm) => {
+        if (killed)
+            return;
+        dir ??= mkdtemp(path.join(os.tmpdir(), "voice-mcp-kokoro-"));
+        const file = path.join(await dir, `${n++}.wav`);
+        await writeFile(file, Buffer.concat([wavHeaderFor(pcm.length, KOKORO_RATE), pcm]));
+        if (killed)
+            return;
+        await new Promise((resolve, reject) => {
+            const child = spawn("/usr/bin/afplay", [file], { stdio: "ignore" });
+            current = child;
+            child.on("error", reject);
+            child.on("close", (code) => (code === 0 || killed ? resolve() : reject(new Error(`afplay failed (exit ${code})`))));
+        });
+    };
+    const cleanup = async () => {
+        if (dir)
+            await rm(await dir, { recursive: true, force: true }).catch(() => { });
+    };
+    return {
+        write: (pcm) => {
+            queue = queue.then(() => playOne(pcm));
+        },
+        finish: async () => {
+            try {
+                await queue;
+            }
+            finally {
+                await cleanup();
+            }
+        },
+        kill: () => {
+            killed = true;
+            current?.kill("SIGKILL");
+            void queue.catch(() => { }).finally(cleanup);
+        },
+    };
+}
+function openPlayer() {
+    const play = which("play");
+    if (play)
+        return soxPlayer(play);
+    if (IS_MAC && isExecutable("/usr/bin/afplay"))
+        return afplayPlayer();
+    throw new SetupError("The Kokoro voice needs SoX's `play` to play audio (`brew install sox`).");
+}
+const silence = (ms) => Buffer.alloc(Math.round((KOKORO_RATE * ms) / 1000) * 2);
+/** Speak `text` with Kokoro. Throws KokoroError (with what's still unspoken) if Kokoro fails. */
+export async function speakKokoro(text, signal) {
+    const chunks = prepareForKokoro(text);
+    if (!chunks.length)
+        return { firstAudioMs: 0, coldStart: false };
+    if (!isKokoroInstalled())
+        throw new KokoroError("the Kokoro voice isn't installed — call voice_setup with kokoro=true", chunks);
+    if (signal?.aborted)
+        throw new CancelledError();
+    const t0 = Date.now();
+    const coldStart = !worker.running;
+    let player = null;
+    let handed = 0; // chunks given to the player
+    let firstAudioMs = 0;
+    try {
+        await worker.start();
+        if (signal?.aborted)
+            throw new CancelledError();
+        player = openPlayer();
+        const p = player;
+        const onAbort = () => p.kill();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            const r = await worker.speak(chunks, (seq, pcm) => {
+                if (seq === 0)
+                    firstAudioMs = Date.now() - t0;
+                p.write(seq < chunks.length - 1 ? Buffer.concat([pcm, silence(GAP_MS)]) : pcm);
+                handed = seq + 1;
+            }, signal);
+            if (r.cancelled || signal?.aborted)
+                throw new CancelledError();
+            await p.finish();
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+        }
+        return { firstAudioMs, coldStart };
+    }
+    catch (e) {
+        player?.kill();
+        if (e instanceof CancelledError || signal?.aborted)
+            throw new CancelledError();
+        if (e instanceof SetupError)
+            throw new KokoroError(e.message, chunks);
+        throw new KokoroError(e instanceof Error ? e.message : String(e), chunks.slice(handed));
+    }
+}
+/** Speak `text` with Kokoro into a 16 kHz mono 16-bit WAV (for doctor and the round-trip tests). */
+export async function synthesizeKokoroToFile(text, outFile) {
+    const chunks = prepareForKokoro(text);
+    if (!isKokoroInstalled())
+        throw new SetupError("the Kokoro voice isn't installed — call voice_setup with kokoro=true");
+    const t0 = Date.now();
+    const coldStart = !worker.running;
+    await worker.start();
+    const parts = [];
+    let firstAudioMs = 0;
+    await worker.speak(chunks, (seq, pcm) => {
+        if (seq === 0)
+            firstAudioMs = Date.now() - t0;
+        parts[seq] = seq < chunks.length - 1 ? Buffer.concat([pcm, silence(GAP_MS)]) : pcm;
+    });
+    const pcm16k = resamplePcm16(Buffer.concat(parts), KOKORO_RATE, 16_000);
+    await writeFile(outFile, Buffer.concat([wavHeaderFor(pcm16k.length, 16_000), pcm16k]));
+    return { firstAudioMs, coldStart };
+}
+// ---------------------------------------------------------------------------
+// Installing (only from voice_setup with kokoro=true, after the user agreed)
+// ---------------------------------------------------------------------------
+/** npm from the same Node installation that runs this server, else from PATH. */
+function findNpm() {
+    const sibling = path.join(path.dirname(process.execPath), process.platform === "win32" ? "npm.cmd" : "npm");
+    return isExecutable(sibling) ? sibling : which("npm");
+}
+/** Install kokoro-js and download the model. Returns a one-line summary. */
+export async function installKokoro(onProgress) {
+    const f = kokoroFiles();
+    await mkdir(f.dir, { recursive: true });
+    if (!existsSync(f.pkg)) {
+        const npm = findNpm();
+        if (!npm)
+            throw new SetupError("npm was not found, so kokoro-js can't be installed. Install Node.js from https://nodejs.org (it includes npm).");
+        const pkgJson = path.join(f.dir, "package.json");
+        // "wx": create it only if it isn't there yet, in one step (no check-then-write race).
+        await writeFile(pkgJson, JSON.stringify({ name: "mac-voice-mcp-kokoro", private: true, type: "module", description: "The optional Kokoro voice for mac-voice-mcp." }, null, 2) + "\n", { flag: "wx" }).catch((e) => {
+            if (e.code !== "EEXIST")
+                throw e;
+        });
+        onProgress?.(`installing kokoro-js ${KOKORO_JS_VERSION} with npm`);
+        log(`Running: npm install kokoro-js@${KOKORO_JS_VERSION} in ${f.dir}`);
+        const r = await run(npm, ["install", "--no-audit", "--no-fund", "--loglevel=error", `kokoro-js@${KOKORO_JS_VERSION}`], {
+            timeoutMs: 20 * 60_000,
+            cwd: f.dir,
+            // npm is a Node script: make sure it finds this Node, even from a GUI app's minimal PATH.
+            env: { PATH: [path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) },
+        });
+        if (r.code !== 0)
+            throw new Error(`npm install kokoro-js failed (exit ${r.code}): ${tail(r.stderr, 4)}`);
+    }
+    await writeFile(f.entry, ENTRY_MJS); // always (re)written: tiny, and it repairs an edited or stale one
+    // Load it once, downloading the model if it isn't there yet. This is also the install's self-test.
+    const hadModel = isKokoroModelPresent();
+    worker.stop();
+    worker.onProgress = onProgress;
+    try {
+        const info = await worker.start({ allowDownload: true });
+        worker.stop(); // the next turn starts it normally (downloads off)
+        return (`Installed the Kokoro voice (${info.voice}${hadModel ? "" : `, downloaded the ~${KOKORO_SIZES_MB[CONFIG.kokoroDtype]} MB model`}). ` +
+            "It's used from the next turn on.");
+    }
+    finally {
+        worker.onProgress = undefined;
+    }
+}