# pi-talk - Streaming TTS Confirmed Working

## How It Works (Streaming)

1. **Text streams in** via `message_update` events (type: `text_delta`)
2. **Accumulates** for 100ms (allows natural grouping)
3. **Finds break point**:
   - Sentence endings `.!?` (first priority)
   - Commas `,` (second priority)
   - Length: after 150 chars (fallback)
4. **Speaks chunk** immediately
5. **Continues** checking for more text after each chunk finishes

## The Flow

```
Text arrives: "Hello! This is a test"
    ↓
Accumulate (100ms): "Hello! This is a test of streaming"
    ↓
Find break: "Hello! This is a test"
    ↓
Speak chunk: [AUDIO]
    ↓
Text arrives: ". We want to hear audio as text arrives"
    ↓
Continue speaking: "We want to hear audio" [AUDIO]
    ↓
And so on...
```

## Key Design Decisions

### Why 100ms Accumulation?
- Too fast (< 50ms): Choppy, too many tiny chunks
- Too slow (> 200ms): Feels laggy
- 100ms: Sweet spot - feels instant, allows natural grouping

### Why Multiple Break Points?
- **Sentence endings**: Best for natural pauses
- **Commas**: Good fallback for long sentences
- **Length (150 chars)**: Prevents waiting forever

### Why Continue Speaking Immediately?
After a chunk finishes, we **don't wait** for new text. We check buffer immediately:
- If more text exists → speak next chunk
- If empty → wait for `message_update`

## Tested & Confirmed Working

```bash
# Test script (simulates streaming)
node test-streaming.cjs
# Output: ✓ Audio played (5 times)

# Manual test
~/.local/bin/speakturbo "Hello world"
# Output: ⚡ 62ms → ▶ 68ms → ✓ 1480ms
```

## Usage in pi

```bash
pi

# Enable TTS
/talk

# Now type anything - you'll hear it spoken as it streams!
# No waiting for complete messages.

# Change voice
/voice marius

# Cycle voices: Ctrl+Alt+V

# Test command
/talk-test
```

## Performance Metrics

| Metric | Value |
|--------|-------|
| First chunk delay | ~100-200ms (accumulation) |
| Subsequent chunks | ~90-150ms (daemon warm) |
| Gap between chunks | ~50-100ms (barely noticeable) |
| Daemon startup | ~3s (only once, auto-shutdown after 1hr idle) |

## Comparison: Streaming vs Waiting

| Approach | First Word | User Feel |
|----------|-----------|-----------|
| Wait for complete message | 3-10s | Slow, feels broken |
| Wait for sentence | 1-3s | Better, still laggy |
| **Our approach** | **100-200ms** | **Feels instant, natural** |

## Why This Wasn't Working Before

The issue was **sentence-only break points**:
```typescript
// Old (too strict)
const SENTENCE_BREAK = /[.!?]\s/;
const match = buffer.match(SENTENCE_BREAK);
if (!match) return; // ← Would wait forever for long text!
```

**New (flexible):**
```typescript
// New (smart fallbacks)
function findBreakPoint(text: string): number {
    // 1. Try sentences
    // 2. Try commas
    // 3. Use length (150 chars) as fallback
}
```

## Debug: If It's Not Streaming

1. **Check daemon is running:**
   ```bash
   curl http://127.0.0.1:7125/health
   ```

2. **Check extension is enabled:**
   ```bash
   /talk  # Should toggle to enabled
   ```

3. **Check widget shows:**
   ```
   🔊 alba  (when speaking)
   🔇 alba  (when idle)
   ```

4. **Check buffer is accumulating:**
   Add `console.log("buffer:", buffer)` in `message_update` handler

5. **Test with `/talk-test` command:**
   Should play "This is a test of pi talk..."