mac-voice-mcp 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-29
+
+### Fixed
+- **Recording broke on Macs without SoX when Bluetooth headphones were connected** ([#6](https://github.com/jeet0007/mac-voice-mcp/issues/6)). Every turn failed with "pure digital silence".
+  - The ffmpeg fallback now records from the input chosen in System Settings (`:default`) instead of device number 0. `VOICE_MCP_FFMPEG_DEVICE` still overrides it.
+  - `voice_setup` treats ffmpeg as a fallback, recommends SoX, and installs it with your OK.
+  - Silence recorded through ffmpeg now points at the input device and SoX, not only at mic permissions.
+- **`voice_setup` notices tools installed since the last check**, such as `brew install sox` run in a terminal, without restarting the app.
+
+## [0.3.0] - 2026-09-28
+
+### Added
+- **Voice conversations stay in voice (Claude Code plugin).** Once you've answered out loud, a plugin hook sends Claude back to reply by voice if it tries to answer in text. It does this at most once per spoken answer, so it can never loop. Voice mode ends when you type, when you don't answer, or when Claude says goodbye with `listen: false`. It's tracked per session and expires after 30 idle minutes. `VOICE_MCP_STAY_IN_VOICE=0` turns the hook off.
+- **`speak_and_listen` with `listen: false`** speaks without opening the microphone, for one-way announcements or a goodbye. It needs only text-to-speech, not the recorder, whisper or a model.
+- **One voice turn at a time across the whole Mac.** Claude Code windows, Claude Desktop and Cursor take turns at the speaker and mic, one turn at a time, so they never talk over each other. A waiting turn reports "waiting for another voice session" and gives up after `VOICE_MCP_LOCK_WAIT_SECONDS` (120) with a clear message. A lock left by a crashed session is taken over. If the cache folder isn't writable, turns go ahead without the lock.
+- **README: an Upgrading section and a Voice mode section, plus a note on testing the plugin from a checkout.**
+
+### Changed
+- **Claude waits longer for you to start talking: 15 seconds, up from 8** (`VOICE_MCP_START_TIMEOUT_SECONDS`), so reading or thinking doesn't end the conversation.
+- **When you don't answer, Claude asks once more, then pauses cleanly.** The "no speech" result now tells Claude that the mic is off, so it tells you to type to carry on rather than to speak.
+
+### Removed
+- The unused `packaging/` folder. `.github/` is the only copy of the workflows.
+
 ## [0.2.0] - 2026-09-28
 
 ### Added

package/README.md

@@ -51,7 +51,7 @@ The server has **two tools and two prompts**:
 | `/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. |
 
-**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 8 seconds, Claude gets "no speech", which it is told never to treat as a yes.
+**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.
 
 **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.
 
@@ -76,7 +76,7 @@ You need **Node.js 22 or newer**. Whichever way you install, run setup once afte
   /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`, plus a skill that teaches Claude how to use voice well and fix common problems. Each plugin version runs the matching npm release.
+  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.
 
 ### By hand
@@ -123,7 +123,7 @@ 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`) | `brew install sox` |
+| 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/` |
 
@@ -160,6 +160,14 @@ One command does everything above: it builds the project, runs setup (asking bef
 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.
@@ -167,6 +175,18 @@ git clone https://github.com/jeet0007/mac-voice-mcp && bash mac-voice-mcp/instal
 - **"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:
+
+- **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.
+
+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.
+
+**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.
+
 ## Getting Claude to sound natural
 
 Guidance reaches Claude through several channels, because each client shows different ones:
@@ -177,6 +197,7 @@ Guidance reaches Claude through several channels, because each client shows diff
 | 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 |
 
 The rules Claude is given:
 
@@ -204,16 +225,18 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 | `VOICE_MCP_RATE` | system rate | Words per minute, e.g. `200`. |
 | `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` | `8` | How long to wait for you to start talking. |
+| `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). |
+| `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 ""`). |
 
 **Speech-to-text**
 
@@ -230,6 +253,12 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 | `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. |
+
 **Models** (whisper.cpp names):
 
 | Model | Size | Good for |
@@ -244,7 +273,7 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 | Symptom | Fix |
 |---|---|
 | "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. |
+| "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. |
@@ -253,6 +282,8 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 | 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 (see [Get a better voice](#then-set-up-and-allow-the-mic)). It's used automatically. |
 | 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
@@ -260,7 +291,7 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 - **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 calls are queued.
+- **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
 
@@ -297,11 +328,14 @@ npm run inspect        # MCP Inspector
 | `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/` | The Claude Code plugin's `/mac-voice-mcp:talk` and `:setup` commands and the `voice-help` skill |
+| `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 the plugin: don't start Claude Code inside this repo.** In this folder, `npx mac-voice-mcp@<this version>` finds the checkout itself instead of downloading the package, can't run it, and the server fails with `CONNECTION_CLOSED`. Start `claude` in any other folder. To try unreleased plugin files (skills, hooks), swap the marketplace to your checkout: run `/plugin marketplace remove mac-voice-mcp`, then `/plugin marketplace add /path/to/checkout`, and install at user scope. The server still comes from npm, so test server changes with `npm test` and `npm run test:voice`.
+
 ### 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.

package/dist/config.js

@@ -31,6 +31,10 @@ const modelName = (process.env.VOICE_MCP_WHISPER_MODEL ?? "base.en").trim();
 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");
 export const CONFIG = {
+    /** Models, the mic lock and hook state live here. */
+    cacheDir: CACHE_ROOT,
+    /** 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
     /**
      * macOS voice name, e.g. "Ava (Premium)" (`say -v '?'` lists them). Unset: the most natural
@@ -47,15 +51,15 @@ export const CONFIG = {
     /** End of turn: stop listening after this much silence once the user has spoken. */
     endSilenceMs: Math.max(300, envNum("VOICE_MCP_END_SILENCE_MS", 1200)),
     /** Give up if the user hasn't started talking within this many seconds. */
-    startTimeoutSeconds: Math.max(1, envNum("VOICE_MCP_START_TIMEOUT_SECONDS", 8)),
+    startTimeoutSeconds: Math.max(1, envNum("VOICE_MCP_START_TIMEOUT_SECONDS", 15)),
     /** Speech must be this many dB above the room's background noise. Lower = more sensitive. */
     speechMarginDb: envNum("VOICE_MCP_SPEECH_MARGIN_DB", 12),
     /** …and never quieter than this absolute level (dBFS). */
     minSpeechDb: envNum("VOICE_MCP_MIN_SPEECH_DB", -48),
     /** Recorder: auto (SoX, else ffmpeg) | sox | ffmpeg. */
     recorder: (process.env.VOICE_MCP_RECORDER?.trim().toLowerCase() || "auto"),
-    /** ffmpeg avfoundation audio input (macOS fallback recorder). */
-    ffmpegDevice: process.env.VOICE_MCP_FFMPEG_DEVICE?.trim() || ":0",
+    /** ffmpeg avfoundation audio input (macOS fallback recorder). ":default" follows the input chosen in System Settings. */
+    ffmpegDevice: process.env.VOICE_MCP_FFMPEG_DEVICE?.trim() || ":default",
     // --- Speech-to-text
     /** whisper.cpp model name (tiny.en, base.en, small.en, large-v3-turbo-q5_0, ...). */
     modelName,

package/dist/index.js

@@ -84,7 +84,10 @@ async function runSetupCli(args) {
 async function runTestCli(text) {
     const prompt = text || "Voice bridge test. Say something after the chime, and I'll print what I heard.";
     try {
-        const result = await speakAndListen(prompt, envNum("VOICE_MCP_TEST_SECONDS", DEFAULT_LISTEN_SECONDS), undefined, (p) => console.error(`  … ${p}`));
+        const result = await speakAndListen(prompt, {
+            listenSeconds: envNum("VOICE_MCP_TEST_SECONDS", DEFAULT_LISTEN_SECONDS),
+            onPhase: (p) => console.error(`  … ${p}`),
+        });
         process.stdout.write(result.text + "\n");
         for (const note of result.notes)
             console.error(note);

package/dist/lock.js

@@ -0,0 +1,162 @@
+/**
+ * One voice turn at a time across every voice-mcp on this Mac — several Claude Code windows,
+ * Claude Desktop and Cursor all share one speaker and one microphone.
+ *
+ * The lock is a file created atomically (O_EXCL) holding the owner's pid and start time.
+ * A lock whose owner has died (or that is implausibly old) is taken over, so a crash never
+ * blocks the mic for good. If the lock can't be used at all (read-only or missing cache
+ * folder), turns go ahead without it rather than failing.
+ */
+import { closeSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import path from "node:path";
+import { CONFIG, debug } from "./config.js";
+import { CancelledError, sleep } from "./proc.js";
+/** Longer than any real turn (speaking, up to two minutes of listening, transcribing). */
+const STALE_AFTER_MS = 10 * 60_000;
+/** A lock file that's still unreadable after this long was never going to be written. */
+const UNREADABLE_GRACE_MS = 5_000;
+const POLL_MS = 250;
+export class MicBusyError extends Error {
+    name = "MicBusyError";
+}
+export const lockFile = () => path.join(CONFIG.cacheDir, "mic.lock");
+function readOwner(file) {
+    try {
+        const o = JSON.parse(readFileSync(file, "utf8"));
+        return Number.isInteger(o.pid) && Number.isFinite(o.since) ? o : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM"; // exists, owned by someone else
+    }
+}
+/** The lock file's identity (inode) if it's stale, otherwise null. */
+function staleIdentity(file, now) {
+    let ino;
+    let mtimeMs;
+    try {
+        ({ ino, mtimeMs } = statSync(file));
+    }
+    catch {
+        return null; // gone already; the next attempt will create it
+    }
+    const owner = readOwner(file);
+    const stale = owner ? !isAlive(owner.pid) || now - owner.since > STALE_AFTER_MS : now - mtimeMs > UNREADABLE_GRACE_MS;
+    return stale ? ino : null;
+}
+/**
+ * Remove a stale lock without ever removing a fresh one someone else just created: move it aside
+ * atomically, check it's the same file we judged stale, and put it back if it isn't.
+ */
+function takeOver(file, ino) {
+    const aside = `${file}.${process.pid}.${Date.now()}.stale`;
+    try {
+        renameSync(file, aside);
+    }
+    catch {
+        return; // another session got there first
+    }
+    try {
+        if (statSync(aside).ino !== ino) {
+            try {
+                linkSync(aside, file); // it was a live lock after all: restore it (fails harmlessly if one exists)
+            }
+            catch {
+                /* a newer lock is already in place */
+            }
+        }
+    }
+    finally {
+        try {
+            unlinkSync(aside);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Remove the file only if it's still ours. */
+function releaseIfOurs(file, me) {
+    const now = readOwner(file);
+    if (!now || now.pid !== me.pid || now.since !== me.since)
+        return;
+    try {
+        unlinkSync(file);
+    }
+    catch {
+        /* already gone */
+    }
+}
+const UNUSABLE = new Set(["EACCES", "EPERM", "EROFS", "ENOENT", "ENOTDIR"]);
+const noLock = () => { };
+/** Wait for the mic, take it, and return the function that gives it back. */
+export async function acquireMicLock(opts = {}) {
+    const file = lockFile();
+    const waitMs = opts.waitMs ?? CONFIG.lockWaitSeconds * 1000;
+    const deadline = Date.now() + waitMs;
+    let waiting = false;
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+    }
+    catch (e) {
+        debug("mic lock unavailable, continuing without it:", e.message);
+        return noLock;
+    }
+    for (;;) {
+        if (opts.signal?.aborted)
+            throw new CancelledError();
+        const me = { pid: process.pid, since: Date.now() };
+        try {
+            const fd = openSync(file, "wx");
+            try {
+                writeSync(fd, JSON.stringify(me));
+            }
+            finally {
+                closeSync(fd);
+            }
+            let released = false;
+            const release = () => {
+                if (released)
+                    return;
+                released = true;
+                process.off("exit", release);
+                releaseIfOurs(file, me);
+            };
+            process.on("exit", release); // a normal shutdown mid-turn still frees the mic
+            return release;
+        }
+        catch (e) {
+            const code = e.code ?? "";
+            if (UNUSABLE.has(code)) {
+                debug("mic lock unavailable, continuing without it:", e.message);
+                return noLock;
+            }
+            if (code !== "EEXIST")
+                throw e;
+        }
+        const ino = staleIdentity(file, Date.now());
+        if (ino !== null) {
+            debug("taking over a stale mic lock");
+            takeOver(file, ino);
+            continue;
+        }
+        if (!waiting) {
+            waiting = true;
+            opts.onWait?.();
+        }
+        if (Date.now() > deadline) {
+            throw new MicBusyError("Another voice session on this Mac (another Claude window, Claude Desktop or Cursor) has been using the " +
+                `speaker and microphone for over ${Math.round(waitMs / 1000)} seconds. ` +
+                "Tell the user on screen, and try again once its current turn is over.");
+        }
+        await sleep(POLL_MS);
+    }
+}

package/dist/server.js

@@ -37,12 +37,23 @@ export function createServer() {
                 .optional()
                 .describe(`Upper limit on how long to listen, in seconds (default ${DEFAULT_LISTEN_SECONDS}, max ${MAX_LISTEN_SECONDS}). ` +
                 "Listening already stops when the user finishes talking, so you rarely need this."),
+            listen: z
+                .boolean()
+                .optional()
+                .describe("Default true. false: only speak, without opening the microphone — for a one-way announcement, " +
+                "or to say goodbye when the user ends voice mode."),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    }, async ({ text_to_speak, listen_seconds }, extra) => {
+    }, async ({ text_to_speak, listen_seconds, listen }, extra) => {
         const progress = progressReporter(extra);
+        const phaseMessage = (phase) => phase === "waiting" ? "waiting for another voice session on this Mac to finish" : phase;
         try {
-            const result = await exclusive(() => speakAndListen(text_to_speak, listen_seconds ?? DEFAULT_LISTEN_SECONDS, extra.signal, (phase) => progress?.(phase)));
+            const result = await exclusive(() => speakAndListen(text_to_speak, {
+                listenSeconds: listen_seconds ?? DEFAULT_LISTEN_SECONDS,
+                listen,
+                signal: extra.signal,
+                onPhase: (phase) => progress?.(phaseMessage(phase)),
+            }));
             return {
                 content: [{ type: "text", text: result.text }, ...result.notes.map((note) => ({ type: "text", text: `\n\n${note}` }))],
                 isError: !result.ok,

package/dist/setup.js

@@ -76,9 +76,21 @@ async function checkRequirements() {
             : { label: "Voice", status: "ok", detail: choice.label });
     }
     const rec = findRecorder();
-    checks.push(rec
-        ? { label: "Recorder", status: "ok", detail: describeRecorder(rec) }
-        : { label: "Recorder", status: brewing ? "installing" : "missing", detail: "SoX is not installed", brew: IS_WIN ? undefined : "sox" });
+    if (!rec) {
+        checks.push({ label: "Recorder", status: brewing ? "installing" : "missing", detail: "SoX is not installed", brew: IS_WIN ? undefined : "sox" });
+    }
+    else if (rec.kind === "ffmpeg" && CONFIG.recorder === "auto") {
+        // Works, but it's the fragile path: recommend SoX, which is what the turn-taking is tuned on.
+        checks.push({
+            label: "Recorder",
+            status: brewing ? "installing" : "optional",
+            detail: `${describeRecorder(rec)}, as a fallback. SoX is recommended: it's more reliable with Bluetooth headsets and other audio devices`,
+            brew: "sox",
+        });
+    }
+    else {
+        checks.push({ label: "Recorder", status: "ok", detail: describeRecorder(rec) });
+    }
     const cli = findWhisperCli();
     const server = findWhisperServer();
     if (cli || server) {
@@ -131,9 +143,11 @@ async function checkRequirements() {
  * @param onProgress optional heartbeat while waiting (used for MCP progress notifications).
  */
 export async function runSetupFlow(install, onProgress) {
+    resetWhichCache(); // see anything installed since the last check (e.g. `brew install sox` in a terminal)
     let checks = await checkRequirements();
     if (install) {
-        const formulae = [...new Set(checks.filter((c) => c.status === "missing" && c.brew).map((c) => c.brew))];
+        // Missing pieces, plus recommended ones (SoX when only ffmpeg is there): the user agreed to install.
+        const formulae = [...new Set(checks.filter((c) => (c.status === "missing" || c.status === "optional") && c.brew).map((c) => c.brew))];
         const brew = findBrew();
         if (formulae.length && brew && !running(brewJob))
             brewJob = startBrewInstall(brew, formulae);
@@ -157,7 +171,7 @@ export async function runSetupFlow(install, onProgress) {
     const lines = [
         `voice-mcp setup — ${ready ? "READY" : installing ? "INSTALLING" : "NOT READY"}`,
         "",
-        ...checks.map((c) => `${icon[c.status]} ${c.label}: ${c.detail}${c.brew && c.status === "missing" ? ` → brew install ${c.brew}` : ""}`),
+        ...checks.map((c) => `${icon[c.status]} ${c.label}: ${c.detail}${c.brew && c.status !== "ok" && c.status !== "installing" ? ` → brew install ${c.brew}` : ""}`),
         IS_MAC ? "• Microphone: macOS asks for permission the first time speak_and_listen listens — click Allow." : "",
     ];
     if (done.length)
@@ -169,6 +183,11 @@ export async function runSetupFlow(install, onProgress) {
     lines.push("");
     if (ready) {
         lines.push("Next: everything is in place — speak_and_listen is ready to use.");
+        const recommended = [...new Set(checks.filter((c) => c.status === "optional" && c.brew).map((c) => c.brew))];
+        if (recommended.length && !install && findBrew()) {
+            lines.push(`Recommended: ask the user whether to brew install ${recommended.join(" ")} (see • above). ` +
+                "Only if they agree, call voice_setup with install=true.");
+        }
         if (checks.some((c) => c.label === "Voice" && c.status === "optional")) {
             lines.push("Mention the optional voice tip (•) to the user once — it makes the voice sound far more natural. Nothing else to do.");
         }

package/dist/texts.js

@@ -30,8 +30,8 @@ export const SERVER_INSTRUCTIONS = [
     '- "(No speech detected …)" means no answer: never treat silence as consent. Ask once more or',
     "  continue with safe work and report on screen.",
     "- Once the user is talking with you by voice, stay in voice: answer every turn with speak_and_listen,",
-    "  not a text reply, until they say stop or start typing.",
-    "- Listening ends on its own when the user stops talking; no need to set listen_seconds.",
+    "  not a text reply, until they say stop (say goodbye with listen: false) or start typing.",
+    "- Listening ends when the user stops talking; listen_seconds is rarely needed.",
     '- If the result includes a "voice-mcp note", follow it.',
     "",
     "Setup: if speak_and_listen says voice-mcp is not set up, call voice_setup (check only), tell the user",
@@ -49,7 +49,9 @@ export const SPEAK_TOOL_DESCRIPTION = [
     "",
     "Once the user is talking with you by voice, keep the conversation in voice: answer each transcript with",
     "another speak_and_listen call (not a text reply) until they say stop or start typing.",
-    'A reply of "(No speech detected …)" means the user did not answer — never treat it as consent.',
+    "To end voice mode, or for a one-way announcement, pass listen: false: it speaks without opening the mic.",
+    'A reply of "(No speech detected …)" means the user did not answer — never treat it as consent. Ask once more;',
+    "if still nothing, stop and say on screen that voice mode is paused and they can type to carry on (not speak: the mic is off).",
     'The "voice-mcp timing" line at the end is diagnostics: ignore it unless the user asks why things feel slow.',
     "If it reports that voice-mcp is not set up, call voice_setup.",
 ].join("\n");
@@ -81,9 +83,11 @@ export const VOICE_MODE_PROMPT = (task) => [
     "  Don't narrate every small action.",
     "- If a transcript is unclear, ask again by voice.",
     "- Confirm by voice before anything destructive, irreversible, or that costs money.",
-    "- If I don't answer, don't assume yes: carry on with safe work or pause, and summarize on screen.",
+    "- If I don't answer, don't assume yes: ask once more out loud. If there's still nothing, pause and summarize",
+    "  on screen, and tell me to type anything to pick up again (the mic is off, so don't tell me to speak).",
     "- Keep writing full details (code, diffs, links) on screen as usual; the voice line is the headline.",
-    '- Stop using voice when I say "stop voice mode", "I\'m back", or start typing again.',
+    '- Stop using voice when I say "stop voice mode", "I\'m back", or start typing again. To end it, say a short',
+    "  goodbye with speak_and_listen and listen: false (it speaks without opening the mic).",
     "",
     SPEECH_RULES,
     "",

package/dist/voice.js

@@ -4,8 +4,9 @@ import os from "node:os";
 import path from "node:path";
 import { chime, findRecorder, listenForTurn, MIC_PERMISSION_HINT, RECORDER_MISSING, speak } from "./audio.js";
 import { CONFIG, debug, DEFAULT_LISTEN_SECONDS, MAX_LISTEN_SECONDS, MAX_SPEAK_CHARS } from "./config.js";
+import { acquireMicLock, MicBusyError } from "./lock.js";
 import { ensureModel } from "./model.js";
-import { SetupError } from "./proc.js";
+import { resetWhichCache, SetupError } from "./proc.js";
 import { prepareSpeech } from "./speech-text.js";
 import { findWhisperCli, findWhisperServer, prewarm, STT_MISSING, transcribe } from "./stt.js";
 /** Everything speak_and_listen needs, checked before saying a word. Never installs anything. */
@@ -16,11 +17,33 @@ async function preflight() {
         throw new SetupError(STT_MISSING);
     return { model: await ensureModel({ download: false }) };
 }
-export async function speakAndListen(textToSpeak, listenSeconds, signal, onPhase) {
-    const seconds = Math.min(MAX_LISTEN_SECONDS, Math.max(1, Number.isFinite(listenSeconds) ? listenSeconds : DEFAULT_LISTEN_SECONDS));
-    const { model } = await preflight();
-    // Load the model into the warm server while we talk, so it's ready when the user finishes.
-    prewarm(model);
+export async function speakAndListen(textToSpeak, opts = {}) {
+    const { signal, onPhase } = opts;
+    const listen = opts.listen !== false;
+    const requested = opts.listenSeconds ?? DEFAULT_LISTEN_SECONDS;
+    const seconds = Math.min(MAX_LISTEN_SECONDS, Math.max(1, Number.isFinite(requested) ? requested : DEFAULT_LISTEN_SECONDS));
+    const model = listen ? (await preflight()).model : null;
+    // Load the model into the warm server now, so it's ready when the user finishes (even if we wait below).
+    if (model)
+        prewarm(model);
+    // Wait for any other voice session on this Mac to finish with the speaker and mic.
+    let release;
+    try {
+        release = await acquireMicLock({ signal, onWait: () => onPhase?.("waiting") });
+    }
+    catch (err) {
+        if (err instanceof MicBusyError)
+            return { ok: false, text: err.message, notes: [] };
+        throw err;
+    }
+    try {
+        return await turn(textToSpeak, seconds, model, signal, onPhase);
+    }
+    finally {
+        release();
+    }
+}
+async function turn(textToSpeak, seconds, model, signal, onPhase) {
     const speech = prepareSpeech(textToSpeak, { maxWords: CONFIG.maxSpeakWords, maxChars: MAX_SPEAK_CHARS });
     const notes = [...speech.notes];
     const tmpDir = await mkdtemp(path.join(os.tmpdir(), "voice-mcp-"));
@@ -30,6 +53,10 @@ export async function speakAndListen(textToSpeak, listenSeconds, signal, onPhase
         onPhase?.("speaking");
         await speak(speech.text, signal);
         const spoke = Date.now() - t0;
+        if (!model) {
+            const text = "(Spoken. The microphone was not opened, because listen was false.)";
+            return { ok: true, text, notes: [...notes, `voice-mcp timing: spoke ${secs(spoke)}`] };
+        }
         await chime("start");
         onPhase?.("listening");
         const tListen = Date.now();
@@ -39,14 +66,23 @@ export async function speakAndListen(textToSpeak, listenSeconds, signal, onPhase
         debug("listen:", heard);
         const timing = (transcribedMs) => timingNote({ spokeMs: spoke, listenedMs: t1 - tListen, talkedSeconds: heard.speechSeconds, transcribedMs });
         if (heard.digitalSilence) {
+            resetWhichCache(); // if the user fixes it by installing SoX, the next turn picks it up
+            const viaFfmpeg = findRecorder()?.kind === "ffmpeg";
             return {
                 ok: false,
-                text: `The microphone returned pure digital silence, which usually means microphone access is blocked. ${MIC_PERMISSION_HINT}`,
+                text: viaFfmpeg
+                    ? "The microphone returned pure digital silence. voice-mcp is recording with ffmpeg because SoX isn't installed, " +
+                        "and ffmpeg may be using a silent or wrong input device (for example after connecting Bluetooth headphones). " +
+                        "Suggest `brew install sox` (or call voice_setup), then try again. If that doesn't help: " +
+                        MIC_PERMISSION_HINT
+                    : `The microphone returned pure digital silence, which usually means microphone access is blocked. ${MIC_PERMISSION_HINT}`,
                 notes,
             };
         }
         const waited = Math.min(CONFIG.startTimeoutSeconds, seconds);
-        const noSpeech = `(No speech detected — the user did not reply within ${waited} seconds.)`;
+        const noSpeech = `(No speech detected — the user did not reply within ${waited} seconds. 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.)";
         if (heard.reason === "no-speech")
             return { ok: true, text: noSpeech, notes: [...notes, timing()] };
         onPhase?.("transcribing");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mac-voice-mcp",
   "mcpName": "io.github.jeet0007/mac-voice-mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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": {