# Advanced TTS MCP Server

A high-quality, feature-rich Text-to-Speech MCP server with native TypeScript implementation. Designed for professional applications requiring natural, expressive speech synthesis with advanced controls and zero external dependencies.

## ✨ Features

### 🎯 **Advanced Voice Control**
- **10 High-Quality Voices** - Male and female voices with distinct personalities
- **Emotion Control** - Neutral, happy, excited, calm, serious, casual, confident
- **Dynamic Pacing** - Natural, conversational, presentation, tutorial, narrative modes
- **Speed & Volume** - Precise control from 0.25x to 3.0x speed, 0.1x to 2.0x volume

### 🚀 **Professional Capabilities**
- **Streaming Audio** - Real-time synthesis and playback
- **Batch Processing** - Handle multiple text segments efficiently  
- **Multiple Formats** - WAV, MP3, FLAC, OGG output support
- **Natural Speech Enhancement** - Automatic pause insertion and emotion markers
- **Queue Management** - Handle multiple concurrent requests

### 🔧 **MCP Integration**
- **6 Powerful Tools** - Complete synthesis, batch processing, voice management
- **2 Rich Resources** - Voice capabilities and usage examples
- **Real-time Status** - Track processing progress and manage requests
- **File Management** - Save, list, and organize audio outputs

## 🚀 Quick Start

### Option 1: Deploy to Smithery.ai (Recommended)

**🎯 One-Click Deployment to Smithery Platform**

1. **Deploy Now**: Visit [Smithery.ai](https://smithery.ai) and import this repository
2. **Configure**: Set your preferred voice and speech settings
3. **Use Instantly**: Access via Claude Desktop or any MCP-compatible client

**Benefits:**
- ✅ Zero setup required
- ✅ Automatic scaling and updates  
- ✅ No model downloads needed
- ✅ Enterprise-grade hosting

**[📋 Full Smithery Deployment Guide →](DEPLOYMENT.md)**

### Option 2: Local Installation

**Prerequisites:**
- Node.js 18+

**Installation:**

1. **Clone the repository**
```bash
git clone https://github.com/samihalawa/advanced-tts-mcp.git
cd advanced-tts-mcp
```

2. **Install dependencies**
```bash
npm install
```

3. **Configure Claude Desktop**

Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "advanced-tts": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/advanced-tts-mcp"
    }
  }
}
```

4. **Start using!**

```bash
# Build TypeScript
npm run build

# Start server
npm start
```

Restart Claude Desktop and start synthesizing with natural, expressive voices.

## 🎙️ Available Voices

| Voice ID | Name | Gender | Description |
|----------|------|--------|-------------|
| `af_heart` | Heart | Female | Warm, friendly voice (default) |
| `af_sky` | Sky | Female | Clear, bright voice |
| `af_bella` | Bella | Female | Elegant, sophisticated voice |
| `af_sarah` | Sarah | Female | Professional, confident voice |
| `af_nicole` | Nicole | Female | Gentle, soothing voice |
| `am_adam` | Adam | Male | Strong, authoritative voice |
| `am_michael` | Michael | Male | Friendly, approachable voice |
| `bf_emma` | Emma | Female | Young, energetic voice |
| `bf_isabella` | Isabella | Female | Mature, expressive voice |
| `bm_lewis` | Lewis | Male | Deep, resonant voice |

## 📚 Usage Examples

### Basic Synthesis
```python
# Simple text-to-speech
await synthesize_speech(
    text="Hello! Welcome to Advanced TTS.",
    voice_id="af_heart"
)
```

### Emotional Expression
```python
# Excited announcement
await synthesize_speech(
    text="This is amazing news! You're going to love this new feature!",
    voice_id="af_heart",
    emotion="excited",
    pacing="conversational",
    speed=1.1
)
```

### Professional Presentation
```python
# Tutorial narration
await synthesize_speech(
    text="Step one: Open your browser. Step two: Navigate to the website.",
    voice_id="am_adam", 
    emotion="calm",
    pacing="tutorial",
    speed=0.9
)
```

### Batch Processing
```python
# Multiple segments with pauses
await batch_synthesize(
    segments=[
        "Welcome to our presentation.",
        "Today we'll cover three main topics.", 
        "Let's begin with the first topic."
    ],
    voice_id="af_sarah",
    emotion="confident",
    pacing="presentation",
    merge_output=True,
    segment_pause=1.0,
    save_file=True
)
```

## 🛠️ Available Tools

### `synthesize_speech`
Convert text to natural speech with full control over voice characteristics.

**Parameters:**
- `text` - Text to synthesize (max 10,000 chars)
- `voice_id` - Voice selection (see table above)
- `speed` - Speech rate (0.25-3.0)
- `emotion` - Voice emotion (neutral, happy, excited, calm, serious, casual, confident)
- `pacing` - Speech style (natural, conversational, presentation, tutorial, narrative, fast, slow)
- `volume` - Audio volume (0.1-2.0)
- `output_format` - File format (wav, mp3, flac, ogg)
- `save_file` - Save to file (boolean)
- `filename` - Custom filename

### `batch_synthesize` 
Process multiple text segments efficiently with optional merging.

**Parameters:**
- `segments` - List of text segments
- `merge_output` - Combine into single file
- `segment_pause` - Pause between segments (0.0-5.0s)
- All synthesis parameters from above

### `get_voices`
Retrieve complete voice information and capabilities.

### `get_status` 
Check processing status for synthesis requests.

### `cancel_request`
Cancel active synthesis operations.

### `list_output_files`
Browse saved audio files with metadata.

## 🎛️ Voice Controls

### Emotions
- **Neutral** - Standard, professional tone
- **Happy** - Upbeat, cheerful expression
- **Excited** - Enthusiastic, energetic delivery
- **Calm** - Relaxed, soothing tone
- **Serious** - Formal, authoritative delivery
- **Casual** - Relaxed, conversational style
- **Confident** - Assured, professional tone

### Pacing Styles  
- **Natural** - Balanced, human-like rhythm
- **Conversational** - Casual discussion pace
- **Presentation** - Professional speaking rhythm
- **Tutorial** - Educational, clear delivery
- **Narrative** - Storytelling pace
- **Fast** - Quick delivery (1.2x base speed)
- **Slow** - Deliberate delivery (0.8x base speed)

## 🎵 Audio Formats

| Format | Quality | Use Case |
|--------|---------|----------|
| **WAV** | Uncompressed | Highest quality, editing |
| **MP3** | Compressed | Web, streaming, sharing |
| **FLAC** | Lossless | Archival, high-quality storage |
| **OGG** | Compressed | Open source alternative |

## 🔧 Configuration

### Environment Variables
```bash
# Model paths (optional)
KOKORO_MODEL_PATH=./kokoro-v1.0.onnx
KOKORO_VOICES_PATH=./voices-v1.0.bin

# Output settings
TTS_OUTPUT_DIR=./audio_output
TTS_MAX_QUEUE_SIZE=100

# Audio settings  
TTS_DEFAULT_VOICE=af_heart
TTS_ENABLE_STREAMING=true
```

### Server Configuration
```python
config = ServerConfig(
    model_path="./kokoro-v1.0.onnx",
    voices_path="./voices-v1.0.bin", 
    output_dir="./audio_output",
    max_queue_size=100,
    enable_streaming=True,
    default_voice="af_heart"
)
```

## 🏗️ Architecture

```
├── src/advanced_tts/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # MCP server implementation  
│   ├── engine.py            # Kokoro TTS engine wrapper
│   ├── models.py            # Data models and validation
│   └── utils.py             # Utility functions
├── pyproject.toml           # Project configuration
├── README.md               # Documentation
└── LICENSE                 # MIT License
```

## 🤝 Contributing

Contributions welcome! Areas for improvement:
- Additional voice models
- Real-time streaming synthesis
- Advanced audio effects
- Multi-language support
- Performance optimizations

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

- **Kokoro TTS** - High-quality neural voice synthesis
- **MCP Protocol** - Seamless AI model integration
- **FastMCP** - Efficient server framework

---

**Developed by [Sami Halawa](https://github.com/samihalawa)**

*Transform your text into natural, expressive speech with Advanced TTS MCP Server.*