mac-voice-mcp 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -5,6 +5,16 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-10-11
+
+### Changed
+- **Docs and the voice-help skill now suggest `small.en` for noisy rooms,** with measured numbers: on real recordings with background noise it got 8% of words wrong instead of 12% with `base.en`, the same in a quiet room, at about 0.3 s per reply. `base.en` stays the default, so nobody gets a 466 MB download they didn't ask for.
+
+### Fixed
+- **`doctor` explains a voice that produces no audio.** Sometimes macOS `say` finishes without error but writes almost no sound (0.1 s for a whole sentence), for example when a voice's speech data is missing. `doctor` used to report that as "0% of words right". Now it tries once more, then says which voice wrote no audio and how to pick another (`VOICE_MCP_VOICE`). This was also behind the speech round trip failing on some CI runs, which now use a fixed classic voice.
+- **A cough or a fan no longer counts as your answer.** For a sound with no words, whisper writes a note like `[gunshot]` (a cough), `[APPLAUSE]` (typing) or `[sound of running]` (a fan), and those notes were passed to Claude as if you'd said them. Now every sound note is dropped, and Claude is told it heard a sound but no words. On 10 noise-only clips (cough, typing, fan, hum, music, a door, breathing, silence), all 10 now come back as no speech.
+- **Sentences whisper invents from videos are dropped**, such as "You can find the link in the description below." or "Thanks for watching!". Only whole sentences that nobody says to a coding assistant; "Thank you." and "Bye." stay.
+
 ## [0.4.1] - 2026-10-10
 
 ### Added
@@ -111,7 +121,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
   - `voice_setup`: checks first, installs only what's missing, and only after you agree.
   - The `setup` and `voice_mode` prompts.
 
-[Unreleased]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.4.2...HEAD
+[0.4.2]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.3.0...v0.3.1

package/dist/audio.js

@@ -1,10 +1,11 @@
 /** Speaking (native TTS), the mic chimes, and listening for one conversational turn. */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 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 { wavSeconds } from "./pcm.js";
 import { activeChildren, CancelledError, run, SetupError, tail, which } from "./proc.js";
 // ---------------------------------------------------------------------------
 // Text-to-speech
@@ -138,20 +139,33 @@ export async function synthesizeToFile(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.");
+    const { voice } = IS_MAC ? await chooseVoice() : { voice: undefined };
+    const once = async () => {
+        let result;
+        if (IS_MAC) {
+            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 wavSeconds(await readFile(outFile));
+    };
+    // Sometimes `say` exits fine but writes (almost) no audio, e.g. when the voice's speech data
+    // isn't available. Try once more, then say so plainly instead of handing silence to whisper.
+    const expected = text.trim().split(/\s+/).length > 2;
+    let seconds = await once();
+    if (expected && seconds < 0.3)
+        seconds = await once();
+    if (expected && seconds < 0.3) {
+        throw new Error(`Text-to-speech wrote only ${seconds.toFixed(2)} s of audio for "${text.slice(0, 40)}…" with ${voice ? `the voice "${voice}"` : "the system voice"}. ` +
+            "That voice may be missing its speech data: pick another with VOICE_MCP_VOICE (list them with `say -v '?'`).");
     }
-    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. */

package/dist/pcm.js

@@ -29,6 +29,23 @@ export function resamplePcm16(pcm, fromRate, toRate) {
     }
     return out;
 }
+/** Seconds of audio in a 16-bit mono WAV file's data chunk (`say` may add chunks before it). 0 if there is none. */
+export function wavSeconds(wav) {
+    if (wav.length < 12 || wav.toString("ascii", 0, 4) !== "RIFF")
+        return 0;
+    let rate = 16_000;
+    let off = 12;
+    while (off + 8 <= wav.length) {
+        const id = wav.toString("ascii", off, off + 4);
+        const size = wav.readUInt32LE(off + 4);
+        if (id === "fmt " && off + 16 <= wav.length)
+            rate = wav.readUInt32LE(off + 12) || rate;
+        if (id === "data")
+            return Math.min(size, wav.length - off - 8) / 2 / rate;
+        off += 8 + size + (size % 2);
+    }
+    return 0;
+}
 /** A 44-byte WAV header for 16-bit mono PCM. */
 export function wavHeaderFor(dataBytes, sampleRate) {
     const h = Buffer.alloc(44);

package/dist/speech-text.js

@@ -112,13 +112,39 @@ export function prepareSpeech(input, opts = {}) {
     return { text: s, notes: noteList };
 }
 /** Remove timestamps and non-speech markers like [BLANK_AUDIO] from whisper output. */
+/**
+ * whisper's notes about sounds rather than words: [BLANK_AUDIO], [MUSIC PLAYING], [gunshot] (for a
+ * cough), [APPLAUSE] (for typing), (sound of running) (for a fan), *laughs*, ♪. Never something the user said.
+ */
+const SOUND_NOTES = /\[[^\]]*\]|\([^)]*\)|\*[^*\n]+\*|[♪♫]+/g;
+/**
+ * Sentences whisper invents from the videos it learned from, typically on noise or a clipped start.
+ * Only whole sentences that nobody says to a coding assistant; "Thank you." and "Bye." are real answers.
+ */
+const STOCK_SENTENCES = [
+    /^(?:thanks|thank you)(?: (?:so|very) much)? for (?:watching|listening)(?: and see you next time)?$/,
+    /^(?:please |don'?t forget to )?(?:like and )?subscribe(?: to (?:my|our|the) channel)?$/,
+    /^(?:you can )?find the links? in the description(?: below)?$/,
+    /^see you in the next (?:video|episode)$/,
+    /^(?:subtitles|captions|transcription|translated|transcribed)(?: by| provided by)? .*$/,
+];
+function isStockSentence(sentence) {
+    const s = sentence.toLowerCase().replace(/[.!?,"“”]/g, "").replace(/\s+/g, " ").trim();
+    return STOCK_SENTENCES.some((re) => re.test(s));
+}
+/** whisper's raw output → just the words: no timestamps, sound notes or invented stock sentences. */
 export function cleanTranscript(raw) {
-    return raw
+    const text = raw
         .split("\n")
         .map((l) => l.replace(/^\s*\[[\d:.\s\->]+\]\s*/, "")) // stray timestamps
         .join(" ")
-        .replace(/\[(?:BLANK_AUDIO|MUSIC|NOISE|SILENCE|INAUDIBLE|_[A-Z_]+_)[^\]]*\]/gi, " ")
-        .replace(/\[\s*(?:silence|music|noise|inaudible)\s*\]/gi, " ")
+        .replace(SOUND_NOTES, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const sentences = text.match(/.+?(?:[.!?]+(?=\s|$)|$)/g) ?? []; // a "." inside "1.2.3" or "Amara.org" doesn't end a sentence
+    return sentences
+        .filter((s) => !isStockSentence(s))
+        .join("")
         .replace(/\s+/g, " ")
         .trim();
 }

package/dist/voice.js

@@ -91,8 +91,14 @@ async function turn(textToSpeak, seconds, model, signal, onPhase) {
         onPhase?.("transcribing");
         const transcript = await transcribe(wav, model, signal);
         const transcribed = Date.now() - t1;
-        if (!transcript)
-            return { ok: true, text: noSpeech, notes: [...notes, timing(transcribed)] };
+        if (!transcript) {
+            // Something was loud enough to sound like speech (a cough, typing, a door), but whisper found no words in it.
+            // Starts with "(No speech detected" so the plugin's voice-mode hook knows the user wasn't heard.
+            const noWords = "(No speech detected — the microphone picked up a sound but no words, probably a cough or background noise. The microphone is now off. " +
+                "Ask once more out loud. If there's still no answer, stop and say on screen that voice mode is paused " +
+                "and they can type anything to carry on — speaking won't work until you call speak_and_listen again.)";
+            return { ok: true, text: noWords, notes: [...notes, timing(transcribed)] };
+        }
         if (heard.reason === "max-duration") {
             const l = heard.levels;
             const f = (n) => (Number.isFinite(n) ? n.toFixed(0) : "?");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mac-voice-mcp",
   "mcpName": "io.github.jeet0007/mac-voice-mcp",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Talk with Claude out loud on your Mac: speaks with macOS `say`, listens for one natural conversational turn, and transcribes on-device with whisper.cpp. An MCP server.",
   "type": "module",
   "bin": {