mac-voice-mcp 0.3.1 → 0.4.1

package/dist/audio.js

@@ -2,8 +2,9 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
-import { CONFIG, debug, IS_MAC, IS_WIN } from "./config.js";
-import { Endpointer, FRAME_BYTES, wavHeader } from "./endpointer.js";
+import { CONFIG, debug, IS_MAC, IS_WIN, log } from "./config.js";
+import { Endpointer, FRAME_BYTES, FRAME_MS, wavHeader } from "./endpointer.js";
+import { KokoroError, kokoroEnabled, speakKokoro, synthesizeKokoroToFile } from "./kokoro.js";
 import { activeChildren, CancelledError, run, SetupError, tail, which } from "./proc.js";
 // ---------------------------------------------------------------------------
 // Text-to-speech
@@ -71,9 +72,33 @@ export function chooseVoice() {
     })();
     return voiceChoice;
 }
+/**
+ * Speak `text` out loud: with the Kokoro voice when it's installed (or VOICE_MCP_TTS=kokoro),
+ * otherwise the built-in voice. If Kokoro fails, the built-in voice says whatever it hadn't said yet.
+ */
 export async function speak(text, signal) {
     if (!text)
-        return;
+        return { engine: "built-in" };
+    if (kokoroEnabled()) {
+        try {
+            return { engine: "kokoro", ...(await speakKokoro(text, signal)) };
+        }
+        catch (err) {
+            if (err instanceof CancelledError)
+                throw err;
+            const reason = err instanceof Error ? err.message : String(err);
+            log(`The Kokoro voice failed, so the built-in voice is speaking instead: ${reason}`);
+            const rest = err instanceof KokoroError ? err.unspoken.join(" ") : text;
+            if (rest)
+                await speakBuiltIn(rest, signal);
+            return { engine: "built-in", fallback: reason };
+        }
+    }
+    await speakBuiltIn(text, signal);
+    return { engine: "built-in" };
+}
+/** macOS `say`, espeak-ng, or Windows SAPI. */
+async function speakBuiltIn(text, signal) {
     const bin = findTts();
     if (!bin)
         throw new SetupError("No text-to-speech engine found. Install espeak-ng (e.g. `sudo apt install espeak-ng`).");
@@ -103,6 +128,32 @@ export async function speak(text, signal) {
         throw new Error(`Text-to-speech failed (exit ${result.code}): ${tail(result.stderr) || "no output"}`);
     }
 }
+/**
+ * Speak `text` into a 16 kHz mono 16-bit WAV instead of the speakers, with the same voice
+ * `speak` uses. For `doctor` and the round-trip tests. A Kokoro failure is an error here, not a fallback.
+ */
+export async function synthesizeToFile(text, outFile) {
+    if (kokoroEnabled())
+        return { engine: "kokoro", ...(await synthesizeKokoroToFile(text, outFile)) };
+    const bin = findTts();
+    if (!bin)
+        throw new SetupError("No text-to-speech engine found.");
+    let result;
+    if (IS_MAC) {
+        const { voice } = await chooseVoice();
+        const args = [...(voice ? ["-v", voice] : []), "-o", outFile, "--file-format=WAVE", "--data-format=LEI16@16000", "-f", "-"];
+        result = await run(bin, args, { input: text, timeoutMs: 60_000 });
+    }
+    else if (/espeak/.test(bin)) {
+        result = await run(bin, ["-w", outFile, "--stdin"], { input: text, timeoutMs: 60_000 });
+    }
+    else {
+        throw new SetupError("Writing speech to a file needs macOS `say` or espeak-ng.");
+    }
+    if (result.code !== 0)
+        throw new Error(`Text-to-speech to file failed (exit ${result.code}): ${tail(result.stderr) || "no output"}`);
+    return { engine: "built-in" };
+}
 /** A short, quiet cue that the mic just opened ("start") or closed ("stop"). macOS only. */
 export async function chime(kind) {
     if (!CONFIG.chime || !IS_MAC)
@@ -152,13 +203,76 @@ function recorderArgs(r) {
         "-ac", "1", "-ar", "16000", "-f", "s16le", "-",
     ];
 }
+/**
+ * Record exactly `seconds` from the microphone into `outFile` (16 kHz mono WAV), no turn-taking.
+ * `onStarted` fires once audio is actually flowing, so a caller can start playback in sync.
+ */
+export async function recordForSeconds(seconds, outFile, onStarted) {
+    const recorder = findRecorder();
+    if (!recorder)
+        throw new SetupError(RECORDER_MISSING);
+    const chunks = [];
+    let bytes = 0;
+    let stderr = "";
+    const wanted = Math.round(seconds * 16000) * 2;
+    const child = spawn(recorder.bin, recorderArgs(recorder), { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    activeChildren.add(child);
+    await new Promise((resolve, reject) => {
+        const stop = () => child.exitCode === null && child.kill("SIGTERM");
+        const safety = setTimeout(stop, (seconds + 10) * 1000);
+        child.stderr.setEncoding("utf8").on("data", (d) => (stderr = (stderr + d).slice(-4000)));
+        child.stdout.on("data", (chunk) => {
+            if (bytes === 0)
+                onStarted?.();
+            if (bytes >= wanted)
+                return;
+            chunks.push(chunk);
+            bytes += chunk.length;
+            if (bytes >= wanted)
+                stop();
+        });
+        child.on("error", (e) => {
+            clearTimeout(safety);
+            activeChildren.delete(child);
+            reject(e);
+        });
+        child.on("close", () => {
+            clearTimeout(safety);
+            activeChildren.delete(child);
+            resolve();
+        });
+    });
+    const pcm = Buffer.concat(chunks).subarray(0, wanted - (wanted % 2));
+    if (!pcm.length)
+        throw new Error(`Recording failed (${describeRecorder(recorder)}). ${tail(stderr)}`.trim());
+    await writeFile(outFile, Buffer.concat([wavHeader(pcm.length), pcm]));
+    let peak = 0;
+    let anyNonZero = false;
+    for (let off = 0; off + FRAME_BYTES <= pcm.length; off += FRAME_BYTES) {
+        let sum = 0;
+        for (let i = off; i < off + FRAME_BYTES; i += 2) {
+            const v = pcm.readInt16LE(i);
+            if (v !== 0)
+                anyNonZero = true;
+            sum += v * v;
+        }
+        peak = Math.max(peak, sum / (FRAME_BYTES / 2));
+    }
+    return { digitalSilence: !anyNonZero, peakDb: peak > 0 ? 10 * Math.log10(peak / 32768 ** 2) : -Infinity };
+}
+/** Audio the mic must have delivered before we tell the user it's open: the recorder is running, and the room's level is known. */
+export const MIC_WARMUP_MS = 250;
 /**
  * Listen for one conversational turn and write it to `outFile` (16 kHz mono WAV).
  * Streams raw PCM from the recorder, runs the endpointer on it live, and stops the
  * recorder the moment the user finishes. Leading and trailing silence are trimmed
  * (keeping a little padding) so whisper gets just the utterance.
+ *
+ * The recorder starts first and `onListening` (the chime) comes only once audio is flowing, so
+ * someone who starts talking right at the chime is never cut off: opening a mic takes a moment,
+ * longer with Bluetooth.
  */
-export async function listenForTurn(maxSeconds, outFile, signal) {
+export async function listenForTurn(maxSeconds, outFile, signal, opts = {}) {
     const recorder = findRecorder();
     if (!recorder)
         throw new SetupError(RECORDER_MISSING);
@@ -173,6 +287,19 @@ export async function listenForTurn(maxSeconds, outFile, signal) {
     let pending = Buffer.alloc(0);
     let reason = null;
     let stderr = "";
+    const warmupFrames = Math.ceil(MIC_WARMUP_MS / FRAME_MS);
+    let announced = false;
+    const announce = () => {
+        announced = true;
+        if (!opts.onListening)
+            return;
+        endpointer.setIgnoring(true);
+        Promise.resolve()
+            .then(opts.onListening)
+            .catch(() => { })
+            // A short tail: the chime's echo fades out of the mic a moment after it ends.
+            .finally(() => setTimeout(() => endpointer.setIgnoring(false), 80));
+    };
     const args = recorderArgs(recorder);
     debug("exec:", recorder.bin, args.join(" "));
     const child = spawn(recorder.bin, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
@@ -200,6 +327,8 @@ export async function listenForTurn(maxSeconds, outFile, signal) {
                 off += FRAME_BYTES;
                 frames.push(frame);
                 reason = endpointer.push(frame);
+                if (!announced && frames.length >= warmupFrames)
+                    announce();
             }
             pending = pending.subarray(off);
             if (reason)

package/dist/config.js

@@ -27,6 +27,23 @@ export function envBool(name, fallback) {
     return !["0", "false", "no", "off"].includes(raw);
 }
 const modelName = (process.env.VOICE_MCP_WHISPER_MODEL ?? "base.en").trim();
+const language = process.env.VOICE_MCP_LANGUAGE?.trim() || (modelName.endsWith(".en") ? "en" : "auto");
+/**
+ * The default hint for English: telling whisper what the conversation is about makes it hear
+ * developer words better ("rebase", "backend", "passed"). Measured: 60 clips, 3 voices, word errors
+ * 3.4% → 2.3% on everyday sentences and 3.8% → 3.1% on jargon, with no words invented in silence.
+ * A plain word list did worse than no hint, so it's a sentence.
+ */
+export const DEVELOPER_PROMPT = "A software developer talks to a coding assistant about the repo: the build, tests, commits, branches, pull requests, npm, JSON, TypeScript, the API and CI.";
+/** VOICE_MCP_WHISPER_PROMPT: unset = the developer hint (English only), "none" = no hint, anything else = that text. */
+function whisperPrompt() {
+    const raw = process.env.VOICE_MCP_WHISPER_PROMPT?.trim();
+    if (raw && ["none", "off", "0", "false"].includes(raw.toLowerCase()))
+        return undefined;
+    if (raw)
+        return raw;
+    return language === "en" ? DEVELOPER_PROMPT : undefined;
+}
 /** Everything this server ever downloads or links lives here, shared by every version and every client. */
 const CACHE_ROOT = process.env.VOICE_MCP_CACHE_DIR?.trim() ||
     path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "mac-voice-mcp");
@@ -36,6 +53,21 @@ export const CONFIG = {
     /** How long a voice turn waits for another session to finish with the mic. */
     lockWaitSeconds: Math.max(1, envNum("VOICE_MCP_LOCK_WAIT_SECONDS", 120)),
     // --- Speaking
+    /**
+     * Which voice engine: auto (default: the Kokoro voice once it's installed, else the built-in one) |
+     * say (always the built-in voice: macOS `say`, espeak-ng elsewhere) | kokoro (Kokoro; voice_setup offers to install it).
+     */
+    tts: (["say", "kokoro"].includes(process.env.VOICE_MCP_TTS?.trim().toLowerCase() ?? "")
+        ? process.env.VOICE_MCP_TTS.trim().toLowerCase()
+        : "auto"),
+    /** Kokoro voice, American (a…) or British (b…) English: af_heart (default), af_bella, am_michael, bf_emma, … */
+    kokoroVoice: process.env.VOICE_MCP_KOKORO_VOICE?.trim() || "af_heart",
+    /** Kokoro speaking speed (1 = normal, 0.5–2). */
+    kokoroSpeed: Math.min(2, Math.max(0.5, envNum("VOICE_MCP_KOKORO_SPEED", 1))),
+    /** Kokoro model precision: fp32 (default: about twice as fast on a CPU, ~330 MB) or q8 (~90 MB, slower). */
+    kokoroDtype: (process.env.VOICE_MCP_KOKORO_DTYPE?.trim().toLowerCase() === "q8" ? "q8" : "fp32"),
+    /** Where the optional Kokoro voice (kokoro-js and its model) is installed. */
+    kokoroDir: process.env.VOICE_MCP_KOKORO_DIR?.trim() || path.join(CACHE_ROOT, "kokoro"),
     /**
      * macOS voice name, e.g. "Ava (Premium)" (`say -v '?'` lists them). Unset: the most natural
      * installed voice for the language (Premium, then Enhanced), else the system voice. "default": always the system voice.
@@ -81,9 +113,9 @@ export const CONFIG = {
     /** Stop the warm whisper-server after this many idle minutes to free memory. */
     serverIdleMinutes: Math.max(1, envNum("VOICE_MCP_SERVER_IDLE_MINUTES", 15)),
     /** Spoken language code ("en", "th", "de", ...) or "auto". Defaults to "en" for *.en models, else "auto". */
-    language: process.env.VOICE_MCP_LANGUAGE?.trim() || (modelName.endsWith(".en") ? "en" : "auto"),
-    /** Optional initial prompt to bias vocabulary (names, jargon). */
-    prompt: process.env.VOICE_MCP_WHISPER_PROMPT?.trim() || undefined,
+    language,
+    /** Initial prompt that biases vocabulary: the developer hint by default (English), or your own (names, jargon). */
+    prompt: whisperPrompt(),
     threads: Math.max(1, Math.floor(envNum("VOICE_MCP_THREADS", Math.min(8, os.cpus().length || 4)))),
     debug: envBool("VOICE_MCP_DEBUG", false),
 };

package/dist/doctor.js

@@ -0,0 +1,185 @@
+/**
+ * `doctor`: an objective self-check of the whole voice pipeline on this Mac.
+ *
+ * Every check ends in PASS / WARN / FAIL against fixed limits, so "does it work?" is answered by
+ * numbers rather than by ear. Results are also written as JSON, so reports from different Macs
+ * and audio setups (headphones, Bluetooth, external mics) can be compared.
+ *
+ *   1. Setup          everything speak_and_listen needs is installed.
+ *   2. Speech → text  the voice speaks a known sentence into a file and whisper transcribes it.
+ *                     Checks the voice and the transcriber without involving the room.
+ *   3. Speaker → mic  the same sentence is spoken live through the speakers (exactly as in a
+ *                     conversation) while the mic records, then transcribed. Checks the real
+ *                     hardware path (skipped with --no-loopback).
+ */
+import { mkdir, mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { chooseVoice, describeRecorder, findRecorder, recordForSeconds, speak, synthesizeToFile } from "./audio.js";
+import { CONFIG, IS_MAC, PKG } from "./config.js";
+import { kokoroEnabled, kokoroVoiceLabel, stopKokoro } from "./kokoro.js";
+import { ensureModel } from "./model.js";
+import { run } from "./proc.js";
+import { runSetupFlow } from "./setup.js";
+import { describeStt, stopWhisperServer, transcribe } from "./stt.js";
+import { wordErrorRate } from "./wer.js";
+export const DOCTOR_SENTENCE = "The build passed and all tests are green. Should I open the pull request now?";
+/** Word error rate limits: [PASS at or below, WARN at or below]; above that is FAIL. */
+export const LIMITS = {
+    /** Clean synthetic speech straight into whisper should be near perfect. */
+    file: [0.1, 0.25],
+    /** Through the air, room noise and a laptop mic make it harder. */
+    loopback: [0.3, 0.5],
+};
+/** Kokoro, model loaded: milliseconds from "speak" to the first sound, [PASS at or below, WARN at or below]. */
+export const FIRST_SOUND_MS = [1500, 3000];
+/** Ends the run early without counting as an unexpected error. */
+class StopChecks extends Error {
+}
+const grade = (wer, [pass, warn]) => (wer <= pass ? "PASS" : wer <= warn ? "WARN" : "FAIL");
+const pct = (x) => `${Math.round(x * 100)}%`;
+/** WAV length in seconds (16 kHz mono 16-bit, 44-byte header). */
+async function wavSeconds(file) {
+    return Math.max(0, ((await stat(file)).size - 44) / 32000);
+}
+/** The default input and output device names (macOS), for the report. Best effort. */
+async function audioDevices() {
+    if (!IS_MAC)
+        return {};
+    try {
+        const r = await run("/usr/sbin/system_profiler", ["SPAudioDataType", "-json"], { timeoutMs: 10_000 });
+        const items = (JSON.parse(r.stdout).SPAudioDataType?.[0]?._items ?? []);
+        const find = (key) => items.find((d) => d[key] === "spaudio_yes")?._name ?? "unknown";
+        return { input: find("coreaudio_default_audio_input_device"), output: find("coreaudio_default_audio_output_device") };
+    }
+    catch {
+        return {};
+    }
+}
+export async function runDoctor(opts = {}) {
+    const say = opts.log ?? (() => { });
+    const checks = [];
+    const add = (c) => {
+        checks.push(c);
+        say(`${c.status.padEnd(4)}  ${c.name}: ${c.detail}`);
+    };
+    const tmp = await mkdtemp(path.join(os.tmpdir(), "voice-mcp-doctor-"));
+    const report = {
+        version: PKG.version,
+        date: new Date().toISOString(),
+        machine: { platform: `${process.platform} ${os.release()}`, arch: process.arch, node: process.version, ...(await audioDevices()) },
+        checks,
+        ok: false,
+    };
+    try {
+        // 1. Setup
+        const setup = await runSetupFlow();
+        add({ name: "Setup", status: setup.ready ? "PASS" : "FAIL", detail: setup.ready ? "everything is installed" : "something is missing — run `setup`" });
+        if (!setup.ready)
+            throw new StopChecks();
+        const voice = await chooseVoice();
+        const recorder = findRecorder();
+        const kokoro = kokoroEnabled();
+        Object.assign(report.machine, {
+            voice: kokoro ? `${kokoroVoiceLabel()}, built-in fallback: ${voice.label}` : voice.label,
+            recorder: recorder ? describeRecorder(recorder) : "none",
+            stt: describeStt(),
+            model: CONFIG.modelPath ?? CONFIG.modelName,
+        });
+        const model = await ensureModel({ download: false });
+        // 2. Speech → text, straight from a file
+        const spoken = path.join(tmp, "spoken.wav");
+        let t = Date.now();
+        const cold = await synthesizeToFile(DOCTOR_SENTENCE, spoken);
+        const synthMs = Date.now() - t;
+        if (cold.engine === "kokoro") {
+            // Again with the voice loaded: how long a normal turn waits before the first sound.
+            const warm = await synthesizeToFile(DOCTOR_SENTENCE, spoken);
+            const ms = warm.firstAudioMs ?? 0;
+            const [pass, warn] = FIRST_SOUND_MS;
+            add({
+                name: "Kokoro voice",
+                status: ms <= pass ? "PASS" : ms <= warn ? "WARN" : "FAIL",
+                detail: `first sound after ${ms} ms (${cold.firstAudioMs ?? 0} ms when the voice had to load first)`,
+                metrics: { firstSoundMs: ms, firstSoundColdMs: cold.firstAudioMs ?? 0 },
+            });
+        }
+        t = Date.now();
+        const heardColdText = await transcribe(spoken, model);
+        const coldMs = Date.now() - t;
+        t = Date.now();
+        const heard = await transcribe(spoken, model); // again, now that the model is loaded
+        const warmMs = Date.now() - t;
+        const fileScore = wordErrorRate(DOCTOR_SENTENCE, heard || heardColdText);
+        const fileStatus = grade(fileScore.wer, LIMITS.file);
+        add({
+            name: "Speech → text",
+            status: fileStatus,
+            detail: `${pct(1 - fileScore.wer)} of words right (heard: "${heard}") — voice ${synthMs} ms, transcribe ${warmMs} ms (first ${coldMs} ms)`,
+            metrics: { wer: fileScore.wer, engine: cold.engine, synthMs, transcribeColdMs: coldMs, transcribeWarmMs: warmMs, audioSeconds: await wavSeconds(spoken) },
+        });
+        // 3. Speaker → mic, through the air
+        if (opts.loopback === false || !IS_MAC) {
+            add({ name: "Speaker → mic", status: "SKIP", detail: IS_MAC ? "skipped (--no-loopback)" : "macOS only" });
+        }
+        else {
+            const recorded = path.join(tmp, "recorded.wav");
+            const seconds = (await wavSeconds(spoken)) + 1.5;
+            let player;
+            const rec = await recordForSeconds(seconds, recorded, () => {
+                // The live voice at full quality, the way speak_and_listen speaks — not the 16 kHz test file.
+                player ??= new Promise((r) => setTimeout(r, 300)).then(() => speak(DOCTOR_SENTENCE));
+            });
+            await player;
+            if (rec.digitalSilence) {
+                add({
+                    name: "Speaker → mic",
+                    status: "FAIL",
+                    detail: "the mic returned pure silence — allow microphone access for this app (System Settings → Privacy & Security → Microphone), or check the input device",
+                    metrics: { peakDb: rec.peakDb },
+                });
+            }
+            else if (rec.peakDb < -50) {
+                add({
+                    name: "Speaker → mic",
+                    status: "WARN",
+                    detail: `almost nothing reached the mic (peak ${Math.round(rec.peakDb)} dB). Expected with headphones — otherwise turn the volume up and run again`,
+                    metrics: { peakDb: rec.peakDb },
+                });
+            }
+            else {
+                t = Date.now();
+                const heardAir = await transcribe(recorded, model);
+                const airMs = Date.now() - t;
+                const air = wordErrorRate(DOCTOR_SENTENCE, heardAir);
+                add({
+                    name: "Speaker → mic",
+                    status: grade(air.wer, LIMITS.loopback),
+                    detail: `${pct(1 - air.wer)} of words right through the air (heard: "${heardAir}"), peak ${Math.round(rec.peakDb)} dB, transcribe ${airMs} ms`,
+                    metrics: { wer: air.wer, peakDb: rec.peakDb, transcribeMs: airMs },
+                });
+            }
+        }
+    }
+    catch (err) {
+        if (!(err instanceof StopChecks)) {
+            add({ name: "Unexpected error", status: "FAIL", detail: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    finally {
+        stopWhisperServer();
+        stopKokoro();
+        await rm(tmp, { recursive: true, force: true });
+    }
+    report.ok = checks.every((c) => c.status !== "FAIL");
+    const dir = opts.reportDir ?? path.join(CONFIG.cacheDir, "doctor");
+    try {
+        await mkdir(dir, { recursive: true });
+        report.reportFile = path.join(dir, `doctor-${report.date.replace(/[:.]/g, "-")}.json`);
+        await writeFile(report.reportFile, JSON.stringify(report, null, 2) + "\n");
+    }
+    catch {
+        /* the report file is a convenience */
+    }
+    return report;
+}

package/dist/endpointer.js

@@ -6,6 +6,7 @@
  *   - once speaking, ends the turn after `endSilenceMs` of quiet
  *   - ignores blips shorter than 300 ms (a cough, a click) and keeps listening
  *   - hard stop at `maxMs`
+ *   - while `ignoring` (our own "mic open" chime is playing), frames are neither speech nor background
  */
 export const SAMPLE_RATE = 16000;
 export const FRAME_MS = 30;
@@ -46,6 +47,8 @@ export class Endpointer {
     lastVoicedFrame = -1;
     /** False while every sample so far has been exactly zero (a blocked mic). */
     anyNonZero = false;
+    /** True while our own chime plays: its sound reaches the mic, but it isn't the user. */
+    ignoring = false;
     constructor(opts) {
         this.opts = opts;
         this.maxFrames = Math.ceil(opts.maxMs / FRAME_MS);
@@ -53,6 +56,12 @@ export class Endpointer {
         this.endSilenceFrames = Math.ceil(opts.endSilenceMs / FRAME_MS);
         this.historySize = Math.max(FLOOR_WINDOW_FRAMES, this.endSilenceFrames, Math.ceil(1000 / FRAME_MS));
     }
+    /** Stop (true) or resume (false) judging frames, e.g. while the "mic open" chime plays. Time still counts. */
+    setIgnoring(on) {
+        this.ignoring = on;
+        if (on && !this.started)
+            this.loudRun = 0;
+    }
     /** Feed one 30 ms frame of 16-bit little-endian PCM; returns a reason once the turn is over. */
     push(frame) {
         const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
@@ -67,6 +76,8 @@ export class Endpointer {
         const rms = Math.sqrt(sumSq / Math.max(1, n)) / 32768;
         const db = Math.max(-100, 20 * Math.log10(rms + 1e-9));
         const idx = this.frames++;
+        if (this.ignoring)
+            return this.timeLimit();
         if (idx >= SETTLE_FRAMES) {
             this.history.push(db);
             if (this.history.length > this.historySize)
@@ -129,6 +140,9 @@ export class Endpointer {
                 }
             }
         }
+        return this.timeLimit();
+    }
+    timeLimit() {
         if (this.frames >= this.maxFrames)
             return this.everStarted ? "max-duration" : "no-speech";
         if (!this.everStarted && this.frames >= this.startTimeoutFrames)

package/dist/index.js

@@ -23,16 +23,25 @@
  *   speech-text.ts  screen text → ear text; transcript clean-up        (pure)
  *   endpointer.ts   turn-taking voice-activity detection               (pure)
  *   audio.ts        TTS, chimes, streaming microphone capture
+ *   kokoro.ts       the optional Kokoro voice: install, warm worker, streaming playback
+ *   kokoro-worker.ts  the process that runs the Kokoro model
+ *   kokoro-text.ts  pronunciation fixes and sentence chunks for Kokoro (pure)
+ *   pcm.ts          PCM conversion and resampling (pure)
  *   model.ts        find / symlink / download the whisper model
  *   stt.ts          warm whisper-server + whisper-cli fallback
  *   setup.ts        requirement checks and consent-based installs
+ *   lock.ts         one voice turn at a time across every session on the Mac
  *   voice.ts        the speak → listen → transcribe round trip
+ *   wer.ts          word error rate (pure)
+ *   doctor.ts       objective self-check with PASS / WARN / FAIL
  *   texts.ts        everything the model reads (rules, instructions, prompts)
  *   server.ts       MCP tools and prompts
  */
 import { createInterface } from "node:readline/promises";
 import { DEFAULT_LISTEN_SECONDS, envNum, log, PKG } from "./config.js";
 import { startServer } from "./server.js";
+import { runDoctor } from "./doctor.js";
+import { stopKokoro } from "./kokoro.js";
 import { runSetupFlow } from "./setup.js";
 import { stopWhisperServer } from "./stt.js";
 import { speakAndListen } from "./voice.js";
@@ -43,7 +52,10 @@ Usage:
   npx -y ${PKG.name}                  Start the MCP server on stdio (what MCP clients run)
   npx -y ${PKG.name} setup            Check what's installed; offers to install what's missing
   npx -y ${PKG.name} setup --install  Install what's missing without asking (brew + model download)
+  npx -y ${PKG.name} setup --kokoro   Install the optional Kokoro voice (about 1 GB on disk)
   npx -y ${PKG.name} test ["text"]    Speak, listen for one turn and print the transcript
+  npx -y ${PKG.name} doctor           Self-check: setup, voice → transcript, speakers → mic (PASS/WARN/FAIL)
+  npx -y ${PKG.name} doctor --no-loopback   …without playing sound through the speakers
   npx -y ${PKG.name} --version
 
 Environment variables (all optional):
@@ -51,10 +63,13 @@ Environment variables (all optional):
   VOICE_MCP_WHISPER_MODEL_PATH     use this ggml model file
   VOICE_MCP_MODEL_SEARCH_PATHS     extra folders to look in for an existing model (":"-separated)
   VOICE_MCP_LANGUAGE               spoken language: en, th, de, … or auto
-  VOICE_MCP_WHISPER_PROMPT         words to bias recognition toward (names, jargon)
+  VOICE_MCP_WHISPER_PROMPT         a sentence about the topic, to hear its words better (default: a developer hint; none = off)
   VOICE_MCP_VOICE / _RATE          macOS say voice and words-per-minute
+  VOICE_MCP_TTS                    auto (Kokoro once installed) | say | kokoro
+  VOICE_MCP_KOKORO_VOICE           Kokoro voice (default af_heart; e.g. af_bella, am_michael, bf_emma)
+  VOICE_MCP_KOKORO_SPEED           Kokoro speed, 0.5–2 (default 1)
   VOICE_MCP_END_SILENCE_MS         pause length that ends your turn (default 1200)
-  VOICE_MCP_START_TIMEOUT_SECONDS  wait this long for you to start talking (default 8)
+  VOICE_MCP_START_TIMEOUT_SECONDS  wait this long for you to start talking (default 15)
   VOICE_MCP_SPEECH_MARGIN_DB       how far above room noise counts as speech (default 12)
   VOICE_MCP_WHISPER_SERVER         0 to always use whisper-cli (no warm server)
   VOICE_MCP_SERVER_IDLE_MINUTES    stop the warm server after this idle time (default 15)
@@ -64,7 +79,9 @@ Environment variables (all optional):
 async function runSetupCli(args) {
     console.error(`${PKG.name} v${PKG.version} on ${process.platform}/${process.arch}, Node ${process.version}\n`);
     const force = args.includes("--install") || args.includes("-y");
-    let outcome = await runSetupFlow(force, (m) => console.error(`  … ${m}`));
+    const kokoro = args.includes("--kokoro");
+    const onProgress = (m) => console.error(`  … ${m}`);
+    let outcome = await runSetupFlow({ install: force, kokoro, onProgress });
     // Interactive terminal: offer to install right away.
     if (!force && !outcome.ready && !outcome.installing && process.stdin.isTTY && /ask the user whether/.test(outcome.report)) {
         console.error(outcome.report.replace(/\nNext:.*$/s, ""));
@@ -73,14 +90,27 @@ async function runSetupCli(args) {
         rl.close();
         if (answer !== "" && !answer.startsWith("y"))
             return 1;
-        outcome = await runSetupFlow(true, (m) => console.error(`  … ${m}`));
+        outcome = await runSetupFlow({ install: true, onProgress });
     }
     // In a terminal we can simply wait for background installs to finish.
     while (outcome.installing)
-        outcome = await runSetupFlow(false, (m) => console.error(`  … ${m}`));
+        outcome = await runSetupFlow({ onProgress });
     console.error(outcome.report);
     return outcome.ready ? 0 : 1;
 }
+async function runDoctorCli(args) {
+    console.error(`${PKG.name} v${PKG.version} doctor — checking the voice pipeline on this machine\n`);
+    const loopback = !args.includes("--no-loopback");
+    if (loopback)
+        console.error("You'll hear a short sentence from the speakers. Keep the room quiet and don't talk.\n");
+    const report = await runDoctor({ loopback, log: (line) => console.error(line) });
+    console.error(`\n${report.ok ? "All checks passed." : "Some checks failed — see the details above."}`);
+    if (report.reportFile)
+        console.error(`Report saved to ${report.reportFile}`);
+    if (args.includes("--json"))
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    return report.ok ? 0 : 1;
+}
 async function runTestCli(text) {
     const prompt = text || "Voice bridge test. Say something after the chime, and I'll print what I heard.";
     try {
@@ -99,6 +129,7 @@ async function runTestCli(text) {
     }
     finally {
         stopWhisperServer();
+        stopKokoro();
     }
 }
 async function main() {
@@ -108,8 +139,9 @@ async function main() {
         case "serve":
             return startServer();
         case "setup":
-        case "doctor":
             process.exit(await runSetupCli(rest));
+        case "doctor":
+            process.exit(await runDoctorCli(rest));
         case "test":
             process.exit(await runTestCli(rest.join(" ").trim()));
         case "-v":