<p align="center">
  <img src="assets/tts-mcp-logo.svg" alt="tts-mcp" width="160">
</p>

Local spoken notifications for Codex. Each message plays through your speakers
and appears in a small always-on-top overlay.

Notifications can include a short source tag. Callers may also request a
persistent overlay with an editable reply area. If `TTS_MCP_REPLY_COMMAND` is
configured, that local command receives `source` and `message` as JSON on stdin;
its stdout is used to prefill the reply area. Without a reply command, the area
starts empty for manual typing.

The popup header also shows the originating working folder (for example,
`TWITCH • ~/code/twitch-mcp`). Callers can override the automatically detected
directory with the `origin_folder` tool argument.

Urgent notifications blink, never auto-close, and must be dismissed with their
**ACCEPT** button.
In a reply editor, **Enter** submits the reply and **Shift+Enter** adds a newline.
Use **OPTIONS** to reset placement. Interactive notifications can be dragged by
their title bar or header, and their position is saved for future messages.
Opening Options pauses the overlay's close countdown until the panel is closed.
The panel also selects the Coqui model used for subsequent local messages and
lowers Spotify to a configurable percentage of its current volume while TTS is
playing. The model menu includes Jenny; LJSpeech VITS, Tacotron2, Glow-TTS,
SpeedySpeech, FastPitch, and Neural HMM variants; EK1 and SAM Tacotron models;
and VCTK VITS or FastPitch with speaker p225. Models download on first use.
Spotify's previous volume is restored when playback ends.

Spotify ducking defaults to 20% of its current volume. The Options choices are
Off, 10%, 20%, 30%, 40%, and 50%. On Linux, tts-mcp prefers a matching PipeWire
stream through `pw-dump` and `wpctl`, then falls back to Spotify's MPRIS volume
property through `busctl`. If neither control path is available, TTS playback
continues without changing Spotify.

The MCP server also exposes:

- `list_voices` — list local presets and optional OpenRouter Flux voices;
- `preview_voices` — play the same short phrase through up to six voices;
- `quit_spotify` — request a graceful Spotify quit, with an explicit forced
  fallback when requested.

Local voice previews include Jenny, LJSpeech VITS, and selected speakers from
the VCTK VITS model. Models are downloaded by Coqui on first use and cached.

## Install

Supports Python 3.11 through 3.14 and requires
[`uv`](https://docs.astral.sh/uv/).

```bash
uv sync
uv run --no-sync agent-notify-setup
codex mcp add agent-notify -- "$(pwd)/.venv/bin/tts-mcp"
```

Restart Codex, then run `/mcp` to check that `agent-notify` is connected. The
setup command downloads and loads the voice model, then opens a real test
notification. Its generated audio is cached for later runs.

Upgrading from the earlier `tts.speak` tool:

```bash
codex mcp remove tts
codex mcp add agent-notify -- "$(pwd)/.venv/bin/tts-mcp"
```

## Turn TTS on or off

Use the **TTS ON / TTS OFF** button in any notification window. Your choice is
saved and applies to future messages; muted messages remain visible so you can
turn speech back on. Turning TTS off also stops the message currently playing,
and the muted window remains open for 15 seconds. A small bar at the bottom
shows the remaining display time. Use the pause button beside the bar to keep a
notification open, then resume the remaining countdown or close it manually.

You can also use the terminal:

```bash
uv run tts-config off
uv run tts-config on
uv run tts-config status
```

## Try it

```bash
uv run tts-notify \
  '{"type":"agent-turn-complete","last-assistant-message":"TTS is ready."}'
```

## Test

```bash
uv run pytest
```

## Optional settings

Set these environment variables when registering the server with
`codex mcp add ... --env NAME=VALUE`:

- `TTS_MCP_MODEL` — Coqui model name; overrides the model saved from Options
- `TTS_MCP_SPEAKER` — speaker ID for a multi-speaker model
- `TTS_MCP_OUTPUT_DIR` — directory for cached WAV files
- `TTS_MCP_OVERLAY=off` — play audio without the overlay
- `TTS_MCP_REPLY_COMMAND` — optional local LLM command used to draft replies
- `TTS_MCP_REPLY_TIMEOUT` — local reply command timeout in seconds (default 120)
- `TTS_MCP_REDUCE_MOTION=on` — replace urgent blinking with a solid alert
- `TTS_MCP_PROVIDER` — `local` (default) or `openrouter`
- `OPENROUTER_API_KEY` — required only for OpenRouter synthesis
- `TTS_MCP_OPENROUTER_MODEL` — defaults to `deepgram/flux-tts:free`
- `TTS_MCP_OPENROUTER_VOICE` — defaults to `flux-bree-en`
- `TTS_MCP_OPENROUTER_FALLBACK=0` — fail instead of using local Coqui

The default model is `tts_models/en/jenny/jenny`. Audio continues to work when
no graphical display is available.

## Optional OpenRouter TTS

Local Coqui remains the default. To use Deepgram Flux TTS through OpenRouter,
set these environment variables on the MCP server:

```bash
TTS_MCP_PROVIDER=openrouter
OPENROUTER_API_KEY=...
TTS_MCP_OPENROUTER_MODEL=deepgram/flux-tts:free
TTS_MCP_OPENROUTER_VOICE=flux-bree-en
```

The remote provider uses OpenRouter's speech endpoint and keeps the generated
WAV in the existing audio cache. Set `TTS_MCP_OPENROUTER_FALLBACK=0` to disable
the default local-Coqui fallback when OpenRouter is unavailable.