mac-voice-mcp 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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
+- **README: a Disclaimer, a Third-party software table and a trademark note.** They spell out what the tool does on your Mac (mic, installs with your consent), that speech recognition can mishear, the license of everything it uses but doesn't bundle, and that the project isn't affiliated with Apple or Anthropic.
+
+### Changed
+- **whisper hears developer talk better.** In English it now gets a one-sentence hint that the conversation is a developer talking to a coding assistant. On 60 test clips read by three voices, word errors fell from 3.4% to 2.3% on everyday sentences and from 3.8% to 3.1% on developer jargon ("rebase", "backend"), and nothing was invented in silence. `VOICE_MCP_WHISPER_PROMPT` replaces the hint with your own, and `none` turns it off.
+- **A shorter README, in the style of popular MCP servers:** what it's for, features, a four-step quick start and the most common fixes. The full guides moved to [`docs/`](docs/): install, voices, usage, configuration, troubleshooting, privacy and security, and development.
+
+### Fixed
+- **The first words of a reply were often lost.** The "mic open" chime played before the recorder had actually started, and opening a mic takes a moment (longer with Bluetooth), so anyone who answered right at the chime lost a word or two. In a test with 20 real recordings, 12 began mid-word, and the cut-off starts led whisper to mishear or invent the rest ("Open a draft PR…" came back as "You can find the link in the description below."). Now the mic opens first and the chime plays once audio is flowing; the chime's own sound is ignored. Re-recorded with the fix, 2 of 20 began mid-word, and whisper's word errors on that voice fell from about 20% to 5% (and from 28% to 12% with background noise).
+
+### Security
+- **MCP SDK 1.32.1** ([GHSA-6qxp-vccf-f47h](https://github.com/advisories/GHSA-6qxp-vccf-f47h)). The advisory is in the SDK's OAuth client, which this server never uses (it only talks over stdio), but `npm audit` flagged every install.
+
 ## [0.4.0] - 2026-10-06
 
 ### Added
@@ -96,7 +121,9 @@ 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.0...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
 [0.3.0]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.2.0...v0.3.0

package/README.md

@@ -24,7 +24,7 @@
 
 ---
 
-Claude says something through your Mac's speakers, listens to your answer the way a person would, and gets back what you said as text. Speech recognition runs on your Mac, so no audio leaves your computer.
+Claude speaks through your Mac's speakers, listens to your answer the way a person would, and gets back what you said as text. Speech recognition runs on your Mac, so no audio leaves your computer.
 
 ```
 Claude ──speak_and_listen("Tests pass. Open the PR?")──▶  🔊 "Tests pass. Open the PR?"
@@ -32,120 +32,47 @@ Claude ──speak_and_listen("Tests pass. Open the PR?")──▶  🔊 "Tests
 Claude ◀──────────────── "Yes, and tag Priya." ─────────  whisper.cpp on your Mac
 ```
 
-It's built for Apple Silicon Macs (M1–M4). Linux works too, with SoX and espeak-ng installed.
+**Perfect for:**
 
-### 🤖 Vibe-coded
-
-> This project was designed and written with Claude, in conversation. A human (me) steered it, tried it on a real Mac and checked the test suite, but most of the code was written by AI. It's a **proof of concept**: it works and has tests, but expect rough edges, and read the code before relying on it for anything important. Issues and pull requests are welcome.
->
-> It's an independent project, not made or endorsed by Anthropic. It works with any MCP client, including Claude Desktop, Claude Code and Cursor.
-
-## How it works
-
-The server has **two tools and two prompts**:
-
-| | What it does |
-|---|---|
-| `speak_and_listen` | Speaks a short message, listens for one conversational turn and returns the transcript. |
-| `voice_setup` | Checks what's installed. After you agree, it installs only what's missing. |
-| `/mcp__voice-mcp__setup` | A guided setup: it checks, asks you, installs, then runs a spoken test. |
-| `/mcp__voice-mcp__voice_mode` | A hands-free session where Claude checks in by voice at natural points. |
+- Long tasks: Claude works quietly and checks in out loud when it needs a decision, so you can step away from the screen.
+- Quick reviews: a 20-second summary of a pull request, then "approve it?"
+- Resting your eyes, or your wrists, after a long day at the keyboard.
+- Thinking out loud: talking a problem through instead of typing it.
 
-**Listening works like a conversation.** A soft chime plays when the mic opens. The server waits for you to start talking and hands back to Claude about a second after you stop. It adjusts to background noise, doesn't cut you off at pauses mid-sentence, and ignores coughs and clicks. If you say nothing for 15 seconds, Claude gets "no speech", which it is told never to treat as a yes.
+## Features
 
-**Replies come back fast.** whisper.cpp's server keeps the speech model loaded between turns, and the model starts loading while Claude is still talking. You don't wait for a model load on each reply. After 15 idle minutes the server shuts down to free memory. It is stopped automatically even if the MCP server crashes.
+- 🔒 **On-device.** whisper.cpp transcribes on your Mac. Recordings are deleted after each turn.
+- 💬 **Natural turn-taking.** A soft chime, then it waits for you to start, and hands back about a second after you stop. No push-to-talk.
+- ⚡ **Fast replies.** A warm whisper.cpp server keeps the model loaded, so transcribing takes a fraction of a second on Apple Silicon.
+- 🗣️ **A natural voice, if you want one.** Uses your best macOS voice, or the optional [Kokoro](docs/voices.md#the-kokoro-voice-optional) neural voice.
+- ✋ **Asks before installing anything.** Setup checks what you already have and reuses it.
+- 🪟 **One mic, many windows.** Claude Code, Claude Desktop and Cursor take turns instead of talking over each other.
+- 📏 **Measured, not guessed.** `doctor` checks the whole pipeline on your Mac and scores it PASS, WARN or FAIL.
 
-**Claude sends text meant to be heard.** The tool description gives Claude rules for writing short spoken sentences. If code, paths, links or markdown still get through, the server rewrites them before speaking and tells Claude, so the next message is cleaner. See [below](#getting-claude-to-sound-natural).
+## Quick start
 
-## Install
+You need a Mac (Apple Silicon recommended) and **Node.js 22 or newer**.
 
-You need **Node.js 22 or newer**. Whichever way you install, run setup once afterwards (see *Then*, below).
+**1. Install.**
 
-### One click
-
-<p>
-  <a href="https://cursor.com/en/install-mcp?name=voice-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1hYy12b2ljZS1tY3BAbGF0ZXN0Il19"><img alt="Add to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg" height="32"></a>
-  <a href="https://insiders.vscode.dev/redirect/mcp/install?name=voice-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mac-voice-mcp%40latest%22%5D%7D"><img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white" height="32"></a>
-  <a href="https://insiders.vscode.dev/redirect/mcp/install?name=voice-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mac-voice-mcp%40latest%22%5D%7D&quality=insiders"><img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=for-the-badge&logo=visualstudiocode&logoColor=white" height="32"></a>
-</p>
-
-### From a marketplace
-
-- **Claude Code plugin marketplace.** This repo is its own marketplace:
+- **Claude Code** (recommended). Install the plugin:
   ```
   /plugin marketplace add jeet0007/mac-voice-mcp
   /plugin install mac-voice-mcp@mac-voice-mcp
   ```
-  The plugin adds `/mac-voice-mcp:setup` and `/mac-voice-mcp:talk`, a skill that teaches Claude how to use voice well and fix common problems, and a hook that keeps a voice conversation in voice (see [Voice mode](#voice-mode)). Each plugin version runs the matching npm release.
-- **The official MCP Registry.** It's listed as [`io.github.jeet0007/mac-voice-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jeet0007/mac-voice-mcp). Apps and directories that read the registry pick it up from there. In VS Code, open the Extensions view (⇧⌘X), search `@mcp mac-voice`, and click **Install**. Smithery, Glama, PulseMCP and mcp.so copy the registry, so it shows up there too.
+- **Cursor or VS Code:** <a href="https://cursor.com/en/install-mcp?name=voice-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1hYy12b2ljZS1tY3BAbGF0ZXN0Il19"><img alt="Add to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg" height="24"></a> <a href="https://insiders.vscode.dev/redirect/mcp/install?name=voice-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mac-voice-mcp%40latest%22%5D%7D"><img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white" height="24"></a>
 
-### By hand
+- **Claude Desktop and other apps:** add `npx -y mac-voice-mcp@latest` as a stdio MCP server. See [Install](docs/install.md#by-hand) for each app.
 
-**Claude Code**
+**2. Set up.** Ask Claude to *"set up voice"* (or run `/mac-voice-mcp:setup`). It checks for SoX, whisper.cpp and a speech model, shows you what's missing, and installs it only after you say yes.
 
-```bash
-claude mcp add voice-mcp -s user -- npx -y mac-voice-mcp@latest
-```
+**3. Allow the microphone.** The first time Claude listens, macOS asks. Click **Allow**.
 
-**Claude Desktop.** Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`, then quit (⌘Q) and reopen the app:
-
-```json
-{
-  "mcpServers": {
-    "voice-mcp": {
-      "command": "npx",
-      "args": ["-y", "mac-voice-mcp@latest"]
-    }
-  }
-}
-```
-
-`@latest` makes npx check for a new release each time the app starts. Without it, npx keeps running whichever version it cached first.
-
-If you get `spawn npx ENOENT`, use the full path from `which npx`, e.g. `"command": "/opt/homebrew/bin/npx"`.
-
-**Cursor.** Add the same `mcpServers` block to `~/.cursor/mcp.json`.
-
-**VS Code.** Run **MCP: Add Server** from the Command Palette, or:
-
-```bash
-code --add-mcp '{"name":"voice-mcp","command":"npx","args":["-y","mac-voice-mcp@latest"]}'
-```
-
-**Any other MCP client.** Run `npx -y mac-voice-mcp@latest` as a stdio server.
-
-### Then: set up and allow the mic
-
-**Run setup once.** Ask Claude to *"set up voice"*. In Claude Code you can also run `/mac-voice-mcp:setup` (plugin) or `/mcp__voice-mcp__setup` (added by hand), or from a terminal run `npx -y mac-voice-mcp@latest setup`.
-
-Setup checks what's already there before it changes anything:
-
-| Needed | Provided by | If it's missing |
-|---|---|---|
-| Voice | macOS `say`, using the most natural voice installed | Nothing to do. For a far better voice, add a free Premium one (see below). |
-| Microphone capture | SoX (`rec`). ffmpeg works as a fallback, but setup recommends SoX | `brew install sox` |
-| Speech-to-text | whisper.cpp (`whisper-cli` and `whisper-server`, Metal-accelerated) | `brew install whisper-cpp` |
-| Speech model | `base.en`, ~140 MB | Downloaded once to `~/.cache/mac-voice-mcp/models/` |
-
-- **Nothing is redone.** Tools already on your PATH are used as they are. If the model is already somewhere on disk (a whisper.cpp checkout, Homebrew's share folder, another tool's cache, or anything Spotlight can find), it's **symlinked**, not downloaded again. `brew install` runs only for the missing formulae.
-- **Nothing happens without your OK.** Claude calls `voice_setup` to check first, shows you the checklist, and asks before calling it with `install=true`.
-- **Slow installs don't time out.** If `brew install whisper-cpp` takes a while, setup reports INSTALLING. The install carries on in the background, and the next check picks up the result.
-
-**Allow the microphone.** The first time Claude listens, macOS asks whether Claude (or Cursor, or your terminal) can use the microphone. Click Allow.
-
-**Get a better voice (recommended).** macOS includes free Premium voices that sound far more natural than the default. Open **System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…**, and download one, for example English → *Ava (Premium)* or *Zoe (Premium)*. The next voice turn uses it automatically. To choose a specific voice, or keep the system voice, see `VOICE_MCP_VOICE` under [Configuration](#configuration).
-
-**Or try the Kokoro voice (optional).** [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) is a small neural voice that sounds close to a person and runs entirely on your Mac. Ask Claude to *"install the Kokoro voice"*, or run `npx -y mac-voice-mcp@latest setup --kokoro`.
-
-- **What it installs:** [kokoro-js](https://github.com/hexgrad/kokoro) with npm into `~/.cache/mac-voice-mcp/kokoro/`, and the model from Hugging Face, once. That's about 1 GB on disk, and nothing is bundled with this package.
-- **How it's used:** once it's installed, every turn uses it, starting with `af_heart`. Pick another voice with `VOICE_MCP_KOKORO_VOICE` (see [Configuration](#configuration)). It speaks sentence by sentence, so it starts talking before the whole reply is generated. Each turn's timing line shows how soon the first sound came.
-- **It can't leave you without a voice.** If Kokoro fails for any reason, the built-in voice takes over mid-sentence, and Claude tells you once.
-- **To stop using it:** set `VOICE_MCP_TTS=say`, or delete `~/.cache/mac-voice-mcp/kokoro/`.
-- **Limits:** English only (American and British voices). It speaks with its own pronunciation rules, which handle common developer words (JSON, `index.ts`, version numbers).
+**4. Talk.** Run `/mac-voice-mcp:talk fix the flaky login test`, or ask Claude to *"check in with me by voice when you need a decision"*. Reply after the chime.
 
 ### Allow voice turns without prompts
 
-By default, Claude Code asks for approval every time Claude wants to speak, which breaks the flow of a conversation. To allow voice turns, add the tool to the `permissions.allow` list in `~/.claude/settings.json`. Use the name that matches how you installed it:
+Claude Code asks for approval every time Claude wants to speak, which breaks the flow of a conversation. To allow voice turns, add the tool to `permissions.allow` in `~/.claude/settings.json`:
 
 ```json
 {
@@ -158,220 +85,75 @@ By default, Claude Code asks for approval every time Claude wants to speak, whic
 }
 ```
 
-The first name is for the plugin, the second for `claude mcp add voice-mcp …`. Leave `voice_setup` out, so installs still ask you first. While `/mac-voice-mcp:talk` runs, voice turns are already allowed.
-
-### Installing from a clone
+The first name is for the plugin, the second for `claude mcp add voice-mcp …`. Leave `voice_setup` out, so installs still ask you first.
 
-One command does everything above: it builds the project, runs setup (asking before installing anything), adds voice-mcp to Claude Desktop (backing up your config first) and to Claude Code, and offers a spoken test. It's safe to re-run, because each step checks first and skips anything already done.
-
-```bash
-git clone https://github.com/jeet0007/mac-voice-mcp && bash mac-voice-mcp/install.sh
-```
-
-## Upgrading
-
-- **Claude Code plugin:** run `/plugin marketplace update mac-voice-mcp`, then open `/plugin`, choose mac-voice-mcp under your installed plugins, and update it. Restart Claude Code. If there's no update option, uninstall and reinstall it.
-- **Everything installed with `mac-voice-mcp@latest`** (Claude Desktop, Cursor, VS Code, `claude mcp add`): restart the app. npx fetches the new release when the server starts.
-- **Configs without `@latest`:** change `mac-voice-mcp` to `mac-voice-mcp@latest` in the config, then restart the app. Otherwise npx keeps running the version it cached first.
-
-Check which version you'd get with `npx -y mac-voice-mcp@latest --version`, and see what changed in the [changelog](CHANGELOG.md). Your model, voice and settings carry over.
-
-## Using it
-
-- **"Work on X and check in with me by voice when you need a decision."** Claude works quietly and only speaks at decision points.
-- **`/mac-voice-mcp:talk fix the flaky login test`** (plugin), or **`/mcp__voice-mcp__voice_mode fix the flaky login test`** (added by hand). Claude reads its plan back to you, then checks in at each checkpoint. Say "stop voice mode" or "I'm back" to end it.
-- **"Read me a 20-second summary of this PR and ask if I should approve it."** Use this for one-off briefings.
-- **Just talk after the chime.** You don't need to hurry or fill silence. If you're still talking at the 30-second safety cap (`listen_seconds`), Claude is told your reply may be cut off and asks you to continue.
-
-### Voice mode
-
-Once you answer out loud, you're in a voice conversation. Claude replies by voice, not in text, until one of these happens:
+## How it works
 
-- **You type something.** You're back at the keyboard.
-- **You say you're done.** Claude says a short goodbye without opening the mic (`speak_and_listen` with `listen: false`).
-- **You don't answer.** After 15 seconds of silence Claude asks once more. If you still don't answer, it pauses and summarizes on screen, and the mic stays off. Type anything, or run `/mac-voice-mcp:talk`, to pick up again.
+The server has two tools and two prompts:
 
-In Claude Code, the plugin enforces this with a hook. If Claude tries to answer in text mid-conversation, the hook sends it back once to answer by voice. If it stops again, the hook lets it. To turn the hook off, add `"VOICE_MCP_STAY_IN_VOICE": "0"` to the `env` block in `~/.claude/settings.json`. Other apps rely on the instructions alone.
+| | What it does |
+|---|---|
+| `speak_and_listen` | Speaks a short message, listens for one conversational turn and returns the transcript. |
+| `voice_setup` | Checks what's installed. After you agree, it installs only what's missing. |
+| `setup` prompt | A guided setup: it checks, asks you, installs, then runs a spoken test. |
+| `voice_mode` prompt | A hands-free session where Claude checks in by voice at natural points. |
 
-**Several sessions, one mic.** Every mac-voice-mcp on your Mac takes turns: Claude Code windows, Claude Desktop and Cursor. While one is speaking or listening, the others wait for that turn to finish (shown as "waiting for another voice session"). They give up after 2 minutes with a message. If a session crashes, the next one takes the mic over.
+Claude is told how to write for the ear: short sentences, no markdown, file names instead of paths. If code or links still get through, the server rewrites them before speaking. In Claude Code, the plugin also keeps a voice conversation in voice until you type. More in [Using it](docs/usage.md).
 
-## Getting Claude to sound natural
+## Troubleshooting
 
-Guidance reaches Claude through several channels, because each client shows different ones:
+Run `npx -y mac-voice-mcp@latest doctor` first. It tests setup, the voice and transcription, and your speakers and mic, and tells you which part fails.
 
-| Channel | Who sees it |
+| Symptom | Fix |
 |---|---|
-| Tool description (rules plus a good and a bad example) | Every client |
-| Server instructions (when to use voice, how to handle replies, setup) | Claude Code (it reads up to 2 KB) |
-| The `voice_mode` and `setup` prompts | Claude Code (as slash commands), Claude Desktop, Cursor |
-| Server-side rewrite plus a `voice-mcp note` back to Claude | Always on |
-| The plugin's `/mac-voice-mcp:talk`, `voice-help` skill and stay-in-voice hook | Claude Code, with the plugin |
+| "microphone returned pure digital silence" | Allow the mic for the app (Claude, Cursor or your terminal) in **System Settings → Privacy & Security → Microphone**, then restart it. |
+| It cuts me off while I'm thinking | Set `VOICE_MCP_END_SILENCE_MS=1800`. |
+| The voice sounds robotic | Download a Premium macOS voice or install Kokoro. See [Voices](docs/voices.md). |
+| It asks for approval every turn | See [Allow voice turns without prompts](#allow-voice-turns-without-prompts). |
 
-The rules Claude is given:
+More in [Troubleshooting](docs/troubleshooting.md).
 
-```
-- 1–3 short sentences, under ~40 words; lead with the outcome, then one question.
-- Plain words only: no markdown, bullets, emoji, code, file paths, URLs, stack traces or tables.
-- Describe code instead of reading it, say file names not paths, round numbers, spell out symbols.
-- Ask one question at a time, answerable in a few words.
-- Put the details (diffs, logs, links) in the on-screen reply, and say so out loud.
-```
+## Documentation
 
-The safety net turns `## Results\n- \`npm test\` ✅ 42/42\n- see /Users/x/repo/src/index.ts:120` into *"Results. npm test 42 of 42. see index.ts."*
+- [Install](docs/install.md): every app, the MCP Registry, installing from a clone, upgrading.
+- [Voices](docs/voices.md): macOS Premium voices and the optional Kokoro voice.
+- [Using it](docs/usage.md): voice mode, several sessions, getting Claude to sound natural.
+- [Configuration](docs/configuration.md): every setting, and the speech models.
+- [Troubleshooting](docs/troubleshooting.md): common problems and known limitations.
+- [Privacy and security](docs/privacy-security.md): what stays on your Mac, and how the project is secured.
+- [Development](docs/development.md): building, testing and releasing.
+- [Changelog](CHANGELOG.md)
 
-Claude Desktop ignores server instructions. To make the rules stick there, paste [`examples/CLAUDE.md`](examples/CLAUDE.md) into *Settings → Profile → personal preferences* or into a Project's instructions. For Claude Code, add it to `CLAUDE.md`. For Cursor, copy [`examples/voice-mcp.mdc`](examples/voice-mcp.mdc) to `.cursor/rules/`.
+### 🤖 Vibe-coded
 
-## Configuration
+> This project was designed and written with Claude, in conversation. A human (me) steered it, tested it on a real Mac and checked the test suite, but most of the code was written by AI. Read the [Disclaimer](#disclaimer) before you rely on it.
 
-Everything is optional. Set these in your client config's `"env": { … }` block, or with `-e NAME=value` in `claude mcp add`.
+## Disclaimer
 
-**Speaking**
+mac-voice-mcp is a free, open-source personal project. It's provided **as is, with no warranty of any kind**, and the authors aren't liable for any damage or loss from using it. See the [LICENSE](LICENSE) for the exact terms. In plain words:
 
-| Variable | Default | |
-|---|---|---|
-| `VOICE_MCP_VOICE` | most natural installed | Unset: the best Premium or Enhanced voice installed for the language, else the system voice. Set a name, e.g. `Ava (Premium)`, `Daniel`, `Kanya` (list them with `say -v '?'`), or `default` to always use the system voice. |
-| `VOICE_MCP_RATE` | system rate | Words per minute, e.g. `200` (macOS voices). |
-| `VOICE_MCP_TTS` | `auto` | `auto`: the [Kokoro voice](#then-set-up-and-allow-the-mic) once it's installed, else the built-in voice. `say`: always the built-in voice. `kokoro`: Kokoro, and setup offers to install it. |
-| `VOICE_MCP_KOKORO_VOICE` | `af_heart` | Kokoro voice. American English starts with `a`, British with `b`, e.g. `af_bella`, `am_michael`, `bf_emma`, `bm_george`. |
-| `VOICE_MCP_KOKORO_SPEED` | `1` | Kokoro speaking speed, `0.5` to `2`. |
-| `VOICE_MCP_KOKORO_DTYPE` | `fp32` | `q8`: a smaller model (~90 MB instead of ~330 MB) that's about half as fast. |
-| `VOICE_MCP_KOKORO_DIR` | `~/.cache/mac-voice-mcp/kokoro` | Where the Kokoro voice is installed. |
-| `VOICE_MCP_MAX_SPEAK_WORDS` | `120` | Longer text is cut at a sentence boundary ("the rest is on screen"). |
-| `VOICE_MCP_CHIME` | `1` | Set to `0` to turn off the mic open/close sounds. |
-| `VOICE_MCP_LOCK_WAIT_SECONDS` | `120` | How long a turn waits while another session on this Mac is using the mic. |
-
-**Listening**
-
-| Variable | Default | |
-|---|---|---|
-| `VOICE_MCP_END_SILENCE_MS` | `1200` | How long a pause ends your turn. Use `1800` if it cuts you off while you think, `800` for snappier replies. |
-| `VOICE_MCP_START_TIMEOUT_SECONDS` | `15` | How long to wait for you to start talking. |
-| `VOICE_MCP_SPEECH_MARGIN_DB` | `12` | How much louder than room noise counts as speech. Raise it in noisy rooms. |
-| `VOICE_MCP_MIN_SPEECH_DB` | `-48` | The quietest level that ever counts as speech (dBFS). |
-| `VOICE_MCP_RECORDER` | `auto` | `sox` or `ffmpeg` (`ffmpeg` is macOS only). `auto` uses SoX, falling back to ffmpeg. |
-| `VOICE_MCP_FFMPEG_DEVICE` | `:default` | Which input ffmpeg records from. `:default` follows System Settings; `:1` picks device 1 (list them with `ffmpeg -f avfoundation -list_devices true -i ""`). |
+- **It turns on your microphone** whenever an AI assistant calls `speak_and_listen`, and plays sound through your speakers.
+- **Speech recognition makes mistakes.** An assistant may act on a misheard word. Check what it heard before you let it do anything you can't undo, like deleting files, pushing code or sending messages.
+- **It installs software on your Mac**, but only after you agree: Homebrew packages, and kokoro-js with npm if you choose the Kokoro voice. Those are separate projects, under their own licenses (below).
+- **There's no guaranteed support.** Issues and pull requests are welcome, and fixed on a best-effort basis.
 
-**Speech-to-text**
+**Trademarks.** Apple, Mac, macOS and Siri are trademarks of Apple Inc. Claude is a trademark of Anthropic. mac-voice-mcp is an independent project, not affiliated with, sponsored or endorsed by Apple or Anthropic.
 
-| Variable | Default | |
-|---|---|---|
-| `VOICE_MCP_WHISPER_MODEL` | `base.en` | Which model to use (see the table below). |
-| `VOICE_MCP_LANGUAGE` | `en` for `*.en` models, otherwise `auto` | `en`, `th`, `ja`, `de`, … |
-| `VOICE_MCP_WHISPER_PROMPT` | — | Words to bias toward: names, product terms, jargon. |
-| `VOICE_MCP_WHISPER_MODEL_PATH` | — | Use this exact `ggml-*.bin` file. |
-| `VOICE_MCP_MODEL_SEARCH_PATHS` | — | Extra folders to check for an existing model (`:`-separated). |
-| `VOICE_MCP_WHISPER_SERVER` | `1` | Set to `0` to always use `whisper-cli`, with no warm server. |
-| `VOICE_MCP_SERVER_IDLE_MINUTES` | `15` | How long the warm server stays up without use. |
-| `VOICE_MCP_THREADS` | min(8, cores) | Number of whisper.cpp threads. |
-| `VOICE_MCP_CACHE_DIR` | `~/.cache/mac-voice-mcp` | Where models are downloaded or symlinked. |
-| `VOICE_MCP_DEBUG` | `0` | Verbose logs with per-turn timings, written to stderr. |
-
-**Claude Code plugin hook.** Set this in the `env` block of `~/.claude/settings.json`, not in the server's config:
-
-| Variable | Default | |
-|---|---|---|
-| `VOICE_MCP_STAY_IN_VOICE` | `1` | Set to `0` to stop the plugin's hook from sending Claude back to answer by voice. |
+### Third-party software
 
-**Models** (whisper.cpp names):
+mac-voice-mcp doesn't bundle any of these. It uses them when they're on your Mac, and installs them only with your consent. Each one comes under its own license.
 
-| Model | Size | Good for |
+| Software | Used for | License |
 |---|---|---|
-| `tiny.en` | 75 MB | Yes/no answers, the lowest latency |
-| `base.en` | 142 MB | **Default.** English conversation. |
-| `small.en` | 466 MB | Noticeably more accurate English |
-| `large-v3-turbo-q5_0` | 547 MB | Other languages, e.g. Thai with `VOICE_MCP_LANGUAGE=th` |
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Not sure what's wrong | Run `npx -y mac-voice-mcp@latest doctor`. It checks setup, the voice and transcription, and your speakers and mic, and says which part fails. |
-| "voice-mcp is not set up yet" | Ask Claude to *set up voice*, or run `npx -y mac-voice-mcp@latest setup`. |
-| "microphone returned pure digital silence" | macOS is blocking the mic for the host app. Go to **System Settings → Privacy & Security → Microphone**, enable Claude / Cursor / your terminal, then restart that app. If the message says it's recording with ffmpeg, the input device is the likelier cause: run `brew install sox`. |
-| No permission prompt ever appears | Run `tccutil reset Microphone <bundle id>` and restart the app. Running `test` in Terminal only gives permission to Terminal, not to Claude Desktop. |
-| It cuts me off while I'm thinking | Set `VOICE_MCP_END_SILENCE_MS=1800` (or up to `2500`). |
-| It never stops listening | The room is too noisy for the defaults. Set `VOICE_MCP_SPEECH_MARGIN_DB=18`, or use a headset. |
-| It hears its own voice | Use headphones, or turn the speaker volume down. It only listens after it finishes speaking, but echo can linger. |
-| "Homebrew: not installed" | Install it from [brew.sh](https://brew.sh). It needs your password, so it can't run from Claude. Then run setup again. |
-| It garbles names or jargon | Set `VOICE_MCP_WHISPER_PROMPT="Priya, Postgres, Kubernetes"`, or switch to `small.en`. |
-| The voice sounds robotic | Download a Premium voice, or install the Kokoro voice (see [Get a better voice](#then-set-up-and-allow-the-mic)). Either is used automatically. |
-| "The Kokoro voice didn't work" | The built-in voice spoke instead. Ask Claude to *check voice setup*, or run `npx -y mac-voice-mcp@latest setup`. To reinstall it, delete `~/.cache/mac-voice-mcp/kokoro/` and run `setup --kokoro`. |
-| It asks for approval every turn | Add the tool to Claude Code's allow list: see [Allow voice turns without prompts](#allow-voice-turns-without-prompts). |
-| "Another voice session on this Mac…" | Another Claude window, Claude Desktop or Cursor held the speaker and mic for over 2 minutes, which means one very long turn. End that conversation, then try again. |
-| Claude keeps answering by voice after I'm done | Type anything, or say "stop voice mode". To switch the plugin's hook off entirely, see [Voice mode](#voice-mode). |
-| Turns feel slow | Each result ends with a timing line, e.g. `spoke 3.1 s · listened 4.0 s · transcribed 0.3 s`. Ask Claude what it says. Transcribing should take well under a second. |
-
-## Known limitations
-
-- **You can't interrupt it.** It finishes speaking, then listens. Barge-in would mean listening while the speakers play, which needs headphones or echo cancellation.
-- **It's macOS-first.** Linux works with SoX and espeak-ng. Windows is untested.
-- **Turn-taking is based on loudness, not a speech model.** It adapts to background noise, but very noisy rooms, music or TV can confuse it. A headset helps, and so do the listening settings above.
-- **One conversation at a time.** There's one speaker and one microphone, so turns from every session on the Mac are queued.
-
-## Privacy and safety
-
-- **Audio stays on your machine.** Recordings go to a temporary file that's deleted after each turn. The only network use is the one-time model download from Hugging Face, plus npm and Hugging Face once more if you install the Kokoro voice. Speaking never downloads anything.
-- **The warm whisper server is local only.** It listens on `127.0.0.1` on a random port, and stops when idle or when this server exits.
-- **Setup can only install known packages.** Its install list is fixed in the code (`sox`, `whisper-cpp`, and `kokoro-js@1.2.1` for the optional voice), so nothing Claude says can make it install anything else. It never uninstalls or modifies other software.
-- **Licenses of the optional Kokoro voice.** The Kokoro model and kokoro-js are Apache-2.0. kokoro-js turns text into sounds with a WebAssembly build of espeak-ng (GPL-3.0), through the `phonemizer` package. None of this is part of mac-voice-mcp (MIT). It's installed on your Mac only if you ask for it.
-
-## Security
-
-- **Secrets:** every push and pull request is scanned for leaked secrets with [TruffleHog](https://github.com/trufflesecurity/trufflehog), and the whole history is scanned before the first push. GitHub secret scanning with push protection is also on.
-- **Dependencies:** [Dependabot](https://docs.github.com/code-security/dependabot) opens weekly update pull requests. CI fails on high-severity advisories (`npm audit`), and dependency review blocks pull requests that add vulnerable packages.
-- **Code:** [CodeQL](https://codeql.github.com) runs with the `security-extended` queries.
-- **Releases:** releases publish through [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/), with no long-lived npm token and a signed provenance attestation for every version.
-
-To report a vulnerability, see [SECURITY.md](SECURITY.md).
-
-## Development
-
-```bash
-npm install
-npm test               # build + unit tests, end-to-end tests over MCP with stub binaries, and release-metadata checks
-npm run audit          # known-vulnerability and signature checks on dependencies
-npm run setup          # check what's installed; offers to install what's missing
-npm run test:voice     # one real speak → listen → transcribe turn
-npm run doctor         # objective self-check on this Mac: PASS / WARN / FAIL per stage, JSON report
-npm run dev:plugin     # try this checkout in Claude Code as the "mac-voice-mcp-dev" plugin
-npm run inspect        # MCP Inspector
-```
-
-| Module | Responsibility |
-|---|---|
-| `config.ts` | Environment settings, logging, the PATH fix-up for GUI apps |
-| `speech-text.ts` | Rewriting screen text for speech, cleaning up transcripts (pure, unit-tested) |
-| `endpointer.ts` | Turn-taking voice-activity detection (pure, unit-tested) |
-| `audio.ts` | Text-to-speech, chimes, streaming mic capture |
-| `kokoro.ts`, `kokoro-worker.ts` | The optional Kokoro voice: install, a warm worker process, sentence-by-sentence playback, fallback |
-| `kokoro-text.ts`, `pcm.ts` | Pronunciation fixes and sentence chunks for Kokoro, PCM conversion (pure, unit-tested) |
-| `model.ts` | Finding, symlinking or downloading the model |
-| `stt.ts` | The warm `whisper-server` with orphan guard, and the `whisper-cli` fallback |
-| `setup.ts` | Requirement checks and consent-based background installs |
-| `lock.ts` | One voice turn at a time across every session on the Mac |
-| `voice.ts`, `server.ts`, `index.ts` | The round trip, the MCP tools and prompts, and the CLI |
-| `skills/`, `hooks/` | The Claude Code plugin's `/mac-voice-mcp:talk` and `:setup` commands, the `voice-help` skill, and the stay-in-voice hook |
-
-The package installs two commands: `mac-voice-mcp` (the one `npx -y mac-voice-mcp` runs), and `voice-mcp`.
-
-**Testing changes.** Three layers; none of them depend on anyone's ears.
-
-1. **`npm test`** runs everywhere, with stub binaries. It covers the MCP tools, turn-taking, setup, the mic lock, the plugin hook and the release metadata.
-2. **The "Speech round trip" CI job** runs on a real Mac. Our own `setup --install` puts in SoX, whisper.cpp and the model. Then `doctor --no-loopback` runs, and `test/roundtrip.test.mjs` speaks known sentences with the real voice and transcribes them with the real whisper.cpp. The build fails if too many words come back wrong or transcription is too slow. The same job then installs the Kokoro voice with `setup --kokoro` and repeats the round trip with it, which also checks how soon Kokoro starts talking. GitHub's Macs have only basic voices and no GPU for whisper.cpp, so the limits there are looser: it guards against breakage, and doctor on a real Mac is the quality bar. The numbers are kept as a build artifact.
-3. **`npm run doctor`** on your own Mac adds the one thing CI can't test, your speakers and microphone. It plays a sentence through the speakers, records it and transcribes it. Each stage gets PASS, WARN or FAIL against fixed limits, and the report is saved under `~/.cache/mac-voice-mcp/doctor/`.
-
-**Trying the plugin from a checkout:** run `npm run dev:plugin`, then the `claude --plugin-dir …` command it prints. This loads a throwaway plugin, "mac-voice-mcp-dev", that runs this checkout's build with `node`. Its own name means it doesn't clash with an installed mac-voice-mcp. It also works inside this repo, where `npx mac-voice-mcp@<this version>` would find the checkout instead of the package and fail with `CONNECTION_CLOSED`.
-
-### Releasing
-
-- **First release:** `bash publish.sh`. It asks before each public step and uses your own GitHub and npm logins. It creates the GitHub repo, publishes to npm, and lists the server in the [official MCP Registry](https://registry.modelcontextprotocol.io), which Smithery, Glama, PulseMCP and mcp.so pick up from.
-- **Later releases:**
-  1. Add a section to `CHANGELOG.md` for the new version, in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format, dated today.
-  2. Run `npm version patch` (bug fixes), `npm version minor` (new features) or `npm version major` (breaking changes), per [semver](https://semver.org). It updates `package.json`, `package-lock.json`, `server.json` and the plugin (including the npm version the plugin runs), commits, and tags `v<version>`.
-  3. Run `git push --follow-tags`.
-
-  The Publish workflow then runs the tests, which also check that every version and the changelog entry match. It publishes to npm with provenance, lists the release in the MCP Registry, and creates a GitHub Release from the changelog section. It needs no secrets: npm and the registry both use GitHub's OIDC identity, once you've set the package's *Trusted Publisher* on npmjs.com (`publish.sh` prints the steps). If a step fails, fix the cause and use **Re-run failed jobs**. Steps that already finished are skipped.
+| [SoX](https://sourceforge.net/projects/sox/) | Recording from the mic, Kokoro playback | GPL-2.0 |
+| [whisper.cpp](https://github.com/ggml-org/whisper.cpp) | Speech-to-text | MIT |
+| [Whisper models](https://huggingface.co/ggerganov/whisper.cpp) (OpenAI) | Speech-to-text | MIT |
+| macOS voices (`say`) | The built-in voice | Apple's macOS license |
+| [kokoro-js](https://github.com/hexgrad/kokoro) (optional) | The Kokoro voice | Apache-2.0 |
+| [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) model (optional) | The Kokoro voice | Apache-2.0 |
+| [espeak-ng](https://github.com/espeak-ng/espeak-ng) (optional, inside kokoro-js) | Turning text into sounds for Kokoro | GPL-3.0 |
+| [ffmpeg](https://ffmpeg.org) (fallback, never installed by setup) | Recording, if SoX is missing | LGPL-2.1 / GPL |
 
 ## License
 
-MIT
+[MIT](LICENSE) © Jeet

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, wavHeader } from "./endpointer.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. */
@@ -260,13 +274,19 @@ export async function recordForSeconds(seconds, outFile, onStarted) {
     }
     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);
@@ -281,6 +301,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 });
@@ -308,6 +341,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");
@@ -96,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/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

@@ -63,7 +63,7 @@ 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)

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

@@ -60,10 +60,10 @@ async function turn(textToSpeak, seconds, model, signal, onPhase) {
             const text = "(Spoken. The microphone was not opened, because listen was false.)";
             return { ok: true, text, notes: [...notes, timingNote({ spokeMs: spoke, spoken })] };
         }
-        await chime("start");
         onPhase?.("listening");
         const tListen = Date.now();
-        const heard = await listenForTurn(seconds, wav, signal);
+        // The chime plays once the mic is really recording, so the first word is never lost.
+        const heard = await listenForTurn(seconds, wav, signal, { onListening: () => chime("start") });
         void chime("stop");
         const t1 = Date.now();
         debug("listen:", heard);
@@ -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.0",
+  "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": {
@@ -33,7 +33,7 @@
     "version": "node scripts/sync-version.mjs && git add server.json .claude-plugin/plugin.json"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "^4.1.0"
   },
   "devDependencies": {