Metadata-Version: 2.4
Name: soliloquy-tts
Version: 0.5.0
Summary: A text-to-speech MCP server powered by Kokoro — gives Claude Code a voice
Project-URL: Homepage, https://github.com/bstovall/soliloquy
Project-URL: Repository, https://github.com/bstovall/soliloquy
Project-URL: Issues, https://github.com/bstovall/soliloquy/issues
Author: Barry Stovall
License: MIT
License-File: LICENSE
Keywords: claude,kokoro,mcp,text-to-speech,tts,voice
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: kokoro>=0.9.4
Requires-Dist: mcp>=1.1.3
Requires-Dist: numpy>=2.0
Requires-Dist: sounddevice>=0.4.6
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Description-Content-Type: text/markdown

# Soliloquy

[![Tests](https://github.com/bstovall/soliloquy/actions/workflows/test.yml/badge.svg)](https://github.com/bstovall/soliloquy/actions/workflows/test.yml)
[![PyPI version](https://img.shields.io/pypi/v/soliloquy-tts)](https://pypi.org/project/soliloquy-tts/)
[![Python](https://img.shields.io/pypi/pyversions/soliloquy-tts)](https://pypi.org/project/soliloquy-tts/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![PyPI downloads](https://img.shields.io/pypi/dm/soliloquy-tts)](https://pypi.org/project/soliloquy-tts/)

A text-to-speech MCP server powered by [Kokoro](https://github.com/hexgrad/kokoro) — gives Claude Code a voice.

**One command to install. No config, no API keys, no setup.**

## Requirements

- **macOS**, **Windows**, or **Linux**
- **Python 3.10+**
- **PortAudio** (audio output library)

| Platform | PortAudio Install |
|----------|------------------|
| macOS | `brew install portaudio` |
| Windows | Bundled with sounddevice (no action needed) |
| Linux | `sudo apt install libportaudio2` |

> **Note:** Installation downloads ~2GB of dependencies (PyTorch, model weights). First run also downloads the Kokoro-82M model from HuggingFace.

## Quick Start

No install needed (requires [uv](https://github.com/astral-sh/uv)):

```bash
# Install uv if you don't have it:
# macOS:   brew install uv
# Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

claude mcp add soliloquy -s user -- uvx soliloquy-tts
```

Or with pip:

```bash
pip install soliloquy-tts
claude mcp add soliloquy -s user -- soliloquy
```

Restart Claude Code after registering. Claude can now speak.

> **Scope:** `-s user` registers Soliloquy globally so it's available in every project. Use `-s local` (or omit the flag) to register it for the current project only.

## How It Works

Soliloquy uses a hybrid architecture to share a single model across multiple Claude Code sessions:

- **First session** loads the Kokoro model and starts a local backend server
- **Additional sessions** detect the running backend and connect as lightweight proxies (near-instant startup, no extra memory)
- If the backend exits, the next session automatically takes over

This is completely transparent — no configuration needed.

## Why Soliloquy?

| | Cloud TTS (ElevenLabs, OpenAI, etc.) | **Soliloquy** |
|---|---|---|
| **Privacy** | Text sent to cloud | Nothing leaves your machine |
| **Cost** | $0.18–15/1M chars | Free forever |
| **Offline** | No | Yes |
| **Usage Limits** | Quotas / rate limits | Unlimited |
| **Latency** | 200–500ms (network) | ~50–100ms (local) |
| **AI Integration** | Developer calls API from code | AI agent decides when to speak |
| **Setup** | API keys + billing | One command, no config |

## Tools

### `speak`

Synthesize and play text aloud.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `text` | *(required)* | Text to speak |
| `voice` | `af_heart` | Voice ID (see below) |
| `speed` | `1.0` | Speed multiplier (0.5 - 2.0) |
| `lang` | `en-us` | Language code |

### `read_aloud`

Read a file aloud directly — Claude just passes the file path, no need to process the content first. Supports plain text and markdown.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `path` | *(required)* | Path to the file to read |
| `voice` | `af_heart` | Voice ID (see below) |
| `speed` | `1.0` | Speed multiplier (0.5 - 2.0) |
| `lang` | `en-us` | Language code |

### `list_voices`

Returns all available voices with language and gender metadata.

## Voices

28 voices across American and British English:

| Voice | Accent | Gender |
|-------|--------|--------|
| af_heart | American | Female | ★ default
| af_alloy | American | Female |
| af_aoede | American | Female |
| af_bella | American | Female |
| af_jessica | American | Female |
| af_kore | American | Female |
| af_nicole | American | Female |
| af_nova | American | Female |
| af_river | American | Female |
| af_sarah | American | Female |
| af_sky | American | Female |
| am_adam | American | Male |
| am_echo | American | Male |
| am_eric | American | Male |
| am_fenrir | American | Male |
| am_liam | American | Male |
| am_michael | American | Male |
| am_onyx | American | Male |
| am_puck | American | Male |
| am_santa | American | Male |
| bf_alice | British | Female |
| bf_emma | British | Female |
| bf_isabella | British | Female |
| bf_lily | British | Female |
| bm_daniel | British | Male |
| bm_fable | British | Male |
| bm_george | British | Male |
| bm_lewis | British | Male |

## Languages

`en-us` (default), `en-gb`, `ja`, `zh`, `es`, `fr`, `hi`, `it`, `pt-br`

## Uninstall / Update

To unregister from Claude Code:

```bash
claude mcp remove soliloquy -s user
```

If using uvx, clear the cache to force a fresh download on next run:

```bash
uv cache clean soliloquy-tts
```

If using pip:

```bash
pip uninstall soliloquy-tts
```

## Development

```bash
git clone https://github.com/bstovall/soliloquy.git
cd soliloquy
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Run the benchmark:

```bash
python scripts/benchmark_tts.py
```

## License

MIT
