Text To Speech

Zero cost, zero dependencies - uses Microsoft Edge TTS (free, no API key) with native TypeScript.

User Experience

🎯 Quick Start: Read Any Document

Keyboard shortcut (fastest):

1. Open any document in VS Code
2. (Optional) Select specific text to read only that portion
3. Press Ctrl+Alt+R (Windows/Linux) or Cmd+Alt+R (macOS)
4. Audio begins playing through the webview player

Command palette:

• Ctrl+Shift+P → "Alex: Read Aloud"

📊 Status Bar Feedback

The status bar shows real-time progress during TTS operations:

🎵 Webview Audio Player

A sleek panel opens with full playback controls:

┌─────────────────────────────────────────────────────────┐
│  Alex TTS Player                                    [×] │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ▶️ ⏹️   ═══════════●══════════   1:23 / 4:56          │
│                                                         │
│  🔊 ────────●────────                                   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Features:

• Progress bar with scrubbing (click/drag to seek)
• Play/Pause button - toggle playback
• Stop button - ends playback and closes panel
• Volume slider - adjust playback volume
• Time display - current position / total duration
• Auto-close - panel closes when playback ends

🎤 Voice Selection

Choose Alex's voice before reading:

1. Ctrl+Shift+P → "Alex: Read with Voice Selection"
2. Quick pick appears:

3. Select voice → reading begins immediately

💾 Save as MP3

Export any document to audio file:

1. Ctrl+Shift+P → "Alex: Save as Audio"
2. Save dialog opens (default name based on document)
3. Progress notification shows synthesis progress
4. Success notification with options:
   • Open File - plays in default audio player
   • Open Folder - reveals in file explorer

Use cases:

• Create podcasts from documentation
• Generate audio for offline learning
• Archive presentations as audio

⏹️ Stop Reading

Multiple ways to stop playback:

• Click status bar (shows $(unmute) icon during playback)
• Press Escape when reading
• Click stop button in webview player
• Close webview panel
• Ctrl+Shift+P → "Alex: Stop Reading"

📝 Smart Markdown Processing

Alex automatically strips markdown formatting for natural speech:

Symbol conversion:

For Master Alex (Promotion Notes)

This skill gives Alex a voice. Version 2.0 uses native TypeScript WebSocket integration with Microsoft Edge TTS, eliminating external dependencies. Reading documents aloud with natural-sounding neural voices.

Version 2.0 Changes:

• Native TypeScript implementation (no Python/MCP dependencies)
• Direct WebSocket connection to Edge TTS endpoint
• Webview-based audio player (cross-platform)
• Integrated as VS Code commands
• Status bar progress feedback

Why promote to Master:

• Universal utility across all projects
• Zero-cost implementation (uses free Edge TTS API)
• No external dependencies (Python, MCP server)
• Accessibility benefits for vision-impaired users
• Integrated into VS Code extension

Dependencies (v2.0):

• ws npm package (WebSocket client)
• VS Code webview API (for audio playback)

Overview

Alex's voice synthesis capability using Microsoft Edge TTS via native TypeScript. Enables reading markdown documents, code files, and text aloud with natural-sounding voices. Fully integrated into the VS Code extension.

Architecture (v2.0)

┌─────────────────────────────────────────────────────────────┐
│                 Alex VS Code Extension                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Commands:                                                   │
│  • Alex: Read Aloud (Ctrl+Alt+R)                            │
│  • Alex: Read with Voice Selection                          │
│  • Alex: Save as Audio                                      │
│  • Alex: Stop Reading                                       │
│                     │                                        │
│                     ▼                                        │
│  ┌─────────────────────────────────────────────┐            │
│  │           ttsService.ts                       │            │
│  │   Native WebSocket to Edge TTS               │            │
│  │   • SSML generation                          │            │
│  │   • Markdown stripping                       │            │
│  │   • Progress callbacks                       │            │
│  └─────────────────┬───────────────────────────┘            │
│                    │                                         │
│                    ▼                                         │
│  ┌─────────────────────────────────────────────┐            │
│  │           audioPlayer.ts                      │            │
│  │   Webview-based playback                     │            │
│  │   • Cross-platform HTML5 Audio               │            │
│  │   • Play/pause/stop controls                 │            │
│  │   • Progress tracking                        │            │
│  └─────────────────────────────────────────────┘            │
│                                                              │
└──────────────────────┬──────────────────────────────────────┘
                       │ WebSocket (wss://)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│               Microsoft Edge TTS Endpoint                    │
│   wss://speech.platform.bing.com/consumer/speech/...        │
├─────────────────────────────────────────────────────────────┤
│  • 400+ neural voices, 90+ languages                        │
│  • Free, no API key required                                │
│  • MP3 output (24kHz, 48kbps)                               │
│  • SSML support for prosody control                         │
└─────────────────────────────────────────────────────────────┘

macOS Offline Fallback: say

macOS ships 30+ built-in neural voices via the say command -- instant, offline, zero-cost. Use as a fallback when Edge TTS is unavailable (no internet, WebSocket blocked) or for quick, lightweight reads.

# Basic usage
say "Hello from Alex"

# Read a file aloud
say -f document.txt

# Save to audio file (AIFF)
say -o output.aiff "Synthesis complete"

# Save as AAC (smaller file)
say -o output.m4a --data-format=aac "Dream state finished"

# Choose a voice (the macOS "Alex" voice is a fun coincidence)
say -v Alex "I am Alex, reading your documentation"

# List all installed voices
say -v '?'

Notification after long operations: Add say calls to signal completion of brain-qa, dream-state, or VSIX packaging:

# After brain-qa completes
node .github/muscles/brain-qa.cjs --mode quick && say "Brain QA complete"

# After dream state
node .github/muscles/brain-qa.cjs --mode all && say "Dream maintenance finished"

Note: The macOS "Alex" voice name is a happy coincidence -- it's one of the highest-quality built-in voices.

Alex Voice Presets

Voice Selection Rationale

Alex's default voice (GuyNeural) was chosen for:

• Clarity: Excellent pronunciation of technical terms
• Neutrality: Not too formal, not too casual
• Distinctiveness: Recognizable as "Alex's voice"
• Consistency: Same voice across all platforms

VS Code Commands

Alex: Read Aloud

Command: alex.readAloud
Keybinding: Ctrl+Alt+R (Windows/Linux), Cmd+Alt+R (macOS)

Reads the current selection or entire document aloud using Alex's default voice.

Behavior:

• If text is selected, reads only the selection
• If no selection, reads the entire document from top
• If no editor open (v2.1.0): offers "Paste from Clipboard" or "Type Text" options
• Markdown files are stripped of formatting for natural speech
• Pasted/typed text is auto-detected for markdown patterns
• Progress shown in status bar
• Click status bar to stop playback

Alex: Read with Voice Selection

Command: alex.readWithVoice

Quick pick to select a voice preset before reading.

Alex: Save as Audio

Command: alex.saveAsAudio

Generate and save speech to an MP3 file. Opens a save dialog for output location.

Alex: Stop Reading

Command: alex.stopReading
Keybinding: Escape (when reading)

Immediately stops current playback.

Implementation Details

Core Files (src/tts/)

Text Preprocessing

The prepareTextForSpeech() function strips markdown:

Code Block Handling

```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" |

### Time Duration Patterns (v2.1.0)

| Input | Spoken As |
|-------|----------|
| `4h` | "4 hours" |
| `30m` | "30 minutes" |
| `15s` | "15 seconds" |
| `2d` | "2 days" |
| `1w` | "1 week" |
| `90min` | "90 minutes" |

### Emoji Pronunciation (v2.1.0)

| Emoji | Spoken As | Context |
|-------|-----------|--------|
| ✅ | "completed" | Status indicators |
| ❌ | "not done" | Status indicators |
| ⚠️ | "warning" | Alerts |
| 📋 | "planned" | Task status |
| 🔄 | "in progress" | Task status |
| ⏳ | "waiting" | Task status |
| 🔥 | "hot" or "high priority" | When followed by "High" |
| 🔓 | "unlocked" | Feature status |
| 💡 | "idea" | Suggestions |
| 🆕 | "new" | Version notes |

**Emoji-Text Deduplication**: When emoji meaning matches following text (e.g., `✅ Complete`), only says it once ("completed", not "completed Complete").

### Table Reading (v2.1.0)

Markdown tables are converted to natural speech:

```markdown
| Name  | Status    |
|-------|----------|
| Alice | ✅ Done   |
| Bob   | 🔄 Active |

Becomes: "Table with 2 columns: Name, Status. Row 1: Name is Alice. Status is completed. Row 2: Name is Bob. Status is in progress."

Version Pattern Intelligence (v2.1.0)

Versions are spoken naturally with context awareness:

Uses negative lookbehind to prevent redundant "version version".

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

Reliability & Long Content Handling (v2.1.0)

The Problem

Edge TTS has undocumented size limits per WebSocket request. Documents over ~3000 characters (approximately 7 minutes of audio) can cause the connection to stall indefinitely, appearing to hang at "Synthesizing..." with no progress.

The Solution: Chunking with Retry

Chunking Strategy:

Chunk Splitting Logic:

1. Split at paragraph boundaries (\n\n) first
2. If still too long, split at sentence boundaries (. or ! or ? )
3. Progress displayed as Synthesizing speech [n/N]...

Retry with Exponential Backoff:

Jitter (0-500ms random) prevents thundering herd on concurrent requests.

Long Content Summarization

For documents over 5 minutes (~750 words), Alex offers to summarize before reading:

This document is approximately 32 minutes long (~4800 words).
Would you like to:
- Read full content (~32 min)
- Summarize for speech (~3 min) ← Recommended

Summarization uses the VS Code Language Model API (GPT-4o preferred) with a target of ~450 words (~3 minutes).

Speaker Warmup Delay

Bluetooth and USB speakers often need time to "wake up" from power-saving mode. A 2-second delay before playback starts ensures the first words aren't clipped:

const SPEAKER_WARMUP_MS = 2000;
// Status shows "Preparing speakers..." during delay

Installation (v2.0)

TTS v2 is built into the Alex VS Code extension. No separate installation required.

Package Dependencies

The extension automatically includes:

• ws (WebSocket client for Edge TTS connection)
• fs-extra (file operations for audio saving)

Verification

After extension update, verify TTS works:

1. Open any document
2. Press Ctrl+Alt+R (Windows/Linux) or Cmd+Alt+R (macOS)
3. Status bar should show "$(unmute) Synthesizing..."
4. Audio should play through webview panel

Usage Patterns

Read Current Document

Press Ctrl+Alt+R to read document aloud
Select text first to read only selection

Generate Audio File

Command Palette → "Alex: Save as Audio"
Choose output location → MP3 saved

Voice Customization

Command Palette → "Alex: Read with Voice Selection"
Choose: Default | Warm | British | Friendly

Edge TTS Technical Reference

WebSocket Endpoint