┌─────────────────────────────────────────────────────────────┐
│                    Alex (VS Code Copilot)                   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  "Alex, read this document aloud"                           │
│                     │                                       │
│                     ▼                                       │
│  ┌─────────────────────────────────────────────┐           │
│  │           TTS MCP Server                     │           │
│  │   ~/.alex/mcp-servers/tts-reader/            │           │
│  └─────────────────┬───────────────────────────┘           │
│                    │                                        │
└────────────────────┼────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                   edge-tts (Python CLI)                     │
├─────────────────────────────────────────────────────────────┤
│  • Microsoft Edge neural voices                             │
│  • 400+ voices, 90+ languages                               │
│  • Free, no API key required                                │
│  • SSML support for prosody control                         │
└─────────────────────────────────────────────────────────────┘
                     │
                     ▼
              ┌─────────────┐
              │  Audio Out  │  (speakers or MP3 file)
              └─────────────┘

{
  "filePath": "path/to/document.md",  // Path to markdown file
  "text": "Text to read aloud",        // OR provide text directly
  "section": "## Overview"             // Optional: read specific section only
}

{}

{
  "voice": "en-US-ChristopherNeural",  // Required: voice ID or preset
  "rate": "+10%",                       // Optional: speed adjustment
  "pitch": "+2Hz"                       // Optional: pitch adjustment
}

{
  "filePath": "document.md",           // Path to markdown file
  "text": "Or provide text directly",  // Alternative to filePath
  "outputPath": "output.mp3"           // Required: where to save MP3
}

---

## Markdown to Speech Processing

### Stripping Rules

| Markdown | Speech Output |
|----------|---------------|
| `# Heading` | "Heading." (pause) |
| `**bold**` | "bold" (emphasis via prosody) |
| `*italic*` | "italic" |
| `` `code` `` | "code" |
| `[link]\(url\)` | "link" |
| `- item` | "Item." |
| `> quote` | "Quote: ..." |
| `---` | (long pause) |

### Code Block Handling

```markdown
```python
def hello():
    print("Hello")

Becomes: "Python code block. Definition hello. Print hello. End code block."

### Symbol-to-Speech Transformations

Symbols are converted to natural speech equivalents:

| Symbol | Spoken As | Example |
|--------|-----------|--------|
| `~` | "approximately" or "about" | ~2 min → "about 2 minutes" |
| `&` | "and" | A & B → "A and B" |
| `@` | "at" | user@email → "user at email" |
| `%` | "percent" | 50% → "50 percent" |
| `+` | "plus" | +10% → "plus 10 percent" |
| `→` | "leads to" or "becomes" | A → B → "A becomes B" |
| `—` | (pause) | word—word → "word (pause) word" |
| `#` | (context-dependent) | #1 → "number 1"; ## → (heading marker) |
| `<` / `>` | "less than" / "greater than" | x > 5 → "x greater than 5" |
| `≥` / `≤` | "greater than or equal" / "less than or equal" | |
| `µ` | "micro" | µg → "microgram" |
| `°` | "degrees" | 37°C → "37 degrees celsius" |
| `±` | "plus or minus" | ±5% → "plus or minus 5 percent" |

**Design Principle**: Would a human reading this aloud say the symbol name, or translate it to meaning? Almost always the latter.

---

## Installation

### Prerequisites

```powershell
# Python 3.8+ required
python -m pip install edge-tts

# Verify installation
edge-tts --list-voices | Select-String "en-US"

~/.alex/mcp-servers/tts-reader/
├── index.js          # MCP server implementation
├── package.json      # Node.js configuration
└── node_modules/     # MCP SDK dependencies

{
  "mcp": {
    "servers": {
      "tts-reader": {
        "command": "node",
        "args": ["~/.alex/mcp-servers/tts-reader/index.js"],
        "name": "Alex TTS Reader"
      }
    }
  }
}

"Alex, read this document aloud"
"Can you read the README?"
"Read the analysis section"

"Save this as an MP3"
"Create an audio version of the documentation"
"Generate a podcast-style reading"

"Use a British accent"
"Speak a bit faster"
"Use a warmer voice"

# Basic text to speech
python -m edge_tts --text "Hello world" --write-media output.mp3

# With voice selection
python -m edge_tts --voice en-US-GuyNeural --text "Hello" --write-media out.mp3

# With prosody control
python -m edge_tts --voice en-US-GuyNeural --rate=+20% --pitch=+5Hz `
  --text "Faster and higher" --write-media out.mp3

# List all voices
python -m edge_tts --list-voices

python -m edge_tts --voice en-US-GuyNeural --file pitch.txt --write-media output.mp3
Start-Process output.mp3

# Play MP3 on Windows
$player = New-Object System.Media.SoundPlayer
$player.SoundLocation = "output.wav"
$player.PlaySync()

# Alternative: Media.SoundPlayer or Windows Media Player
Start-Process -FilePath "output.mp3"