# Girikon TTS — API Endpoints Comparison

## Overview

Girikon TTS provides three WebSocket endpoints, each optimized for different use cases:

| Version | Endpoint | Engine | Best For |
|---------|----------|--------|----------|
| **V1** | `/ws/tts` or `/ws/tts/v1` | Koyal/Piper + Emotion Planner | Full emotion-aware synthesis with automatic prosody |
| **V2** | `/ws/tts/v2` | Orpheus V2 | Direct Orpheus access with emotion tagging |
| **V3** | `/ws/tts/v3` or `/v3` | Koyal V3 | Latest model with custom instructions |

---

## Quick Comparison

### V1: Full Pipeline (Emotion-Aware)

**Pipeline:**
```
Text → Clean → Normalize → Transliterate → Emotion Plan → Synthesize → Post-process → Stream
```

**Features:**
- ✅ Automatic emotion planning per sentence
- ✅ Text normalization (numbers, dates, abbreviations)
- ✅ Transliteration (Latin → Devanagari)
- ✅ Emotion-aware prosody control
- ✅ Inter-chunk pauses based on emotion
- ✅ Post-processing (highpass, de-ess, LUFS)
- ✅ Micro lead-in for low latency

**Use When:**
- You want the best natural-sounding speech
- You need emotion-aware delivery
- You want automatic text processing
- Low latency is important

**Payload:**
```json
{
  "text": "Sir, सबसे पहले तो आपका बहुत-बहुत शुक्रिया कि आपने inquiry की।",
  "lang": "hi",
  "speaker": "ankur",
  "stream_format": "pcm"
}
```

---

### V2: Orpheus Passthrough

**Pipeline:**
```
Text → Emotion Plan (server) → Tag Emotions → Orpheus V2 → Stream
```

**Features:**
- ✅ Server-side emotion tagging (injected as `<emotion>` tags)
- ✅ Direct Orpheus V2 access
- ✅ Advanced Orpheus parameters (speed, repetition_penalty, pitch_bias_st)
- ✅ No text normalization/transliteration
- ✅ No post-processing

**Use When:**
- You want direct Orpheus control
- You have custom emotion tagging logic
- You need advanced Orpheus parameters
- You want to bypass text processing

**Payload:**
```json
{
  "text": "कृपया ध्यान दें, ट्रेन नंबर बारह सौ पाँच आ रही है।",
  "voice": "Ankur",
  "repetition_penalty": 1.2,
  "speed": 1.2,
  "gain_db": 0.0,
  "pitch_bias_st": 0.0
}
```

**Orpheus Parameters:**
| Parameter | Default | Range | Effect |
|-----------|---------|-------|--------|
| `repetition_penalty` | 1.2 | 0.6–2.0 | Prevents model repetition |
| `speed` | 1.2 | 1.0–3.0 | Speech speed multiplier |
| `gain_db` | 0.0 | -20 to +20 | Output loudness |
| `pitch_bias_st` | 0.0 | -12 to +12 | Pitch shift in semitones |

---

### V3: Koyal V3 Direct

**Pipeline:**
```
Text → Normalize → Split Segments → Koyal V3 → Stream
```

**Features:**
- ✅ Latest Koyal V3 model
- ✅ Optional custom instructions/prompts
- ✅ Minimal server processing (just normalization)
- ✅ Automatic segmentation (280 chars / 80 words max)
- ✅ Direct model control

**Use When:**
- You want the latest model
- You need custom instructions
- You want minimal server overhead
- You're building custom emotion logic

**Payload:**
```json
{
  "input": "कृपया ध्यान दें, ट्रेन नंबर बारह सौ पाँच आ रही है।",
  "voice": "shivani",
  "instructions": "Speak in a calm, reassuring tone.",
  "response_format": "pcm"
}
```

**Voice Aliases:**
- `shivani`, `muskaan`, `riya`, `tara`, `anika`

---

## Event Flow Comparison

### V1 Events
```
start → format → plan → chunk_audio (streaming) → step_timings → latency → done
```

### V2 Events
```
start → plan → format → chunk_audio (streaming) → latency → done
```

### V3 Events
```
start → plan → format → chunk_audio (streaming) → latency → done
```

---

## Voice Mapping

### V1 (Piper/Koyal)
| Alias | Voice | Sample Rate |
|-------|-------|-------------|
| `ankur` | Ankur (HI_EN) | 22050 Hz |
| `shweta` | Shweta (HI_EN) | 22050 Hz |

### V2 (Orpheus V2)
| Alias | Model | Upstream Voice |
|-------|-------|----------------|
| `Ankur` / `ankur` / `male` | `koyel-v2/male` | Hindi (Male) |
| `Shweta` / `shweta` / `female` | `koyel-v2/female` | Hindi (Female) |

### V3 (Koyal V3)
| Alias | Voice |
|-------|-------|
| `shivani` | shivani |
| `muskaan` | muskaan |
| `riya` | riya |
| `tara` | tara |
| `anika` | anika |

---

## Authentication

All endpoints support the same authentication methods:

1. **Query Parameter:** `?api_key=YOUR_KEY`
2. **Authorization Header:** `Authorization: Bearer YOUR_KEY`
3. **Custom Header:** `x-api-key: YOUR_KEY`
4. **First Message:** `{"api_key": "YOUR_KEY", ...}`

---

## Common Parameters

### V1 Only
| Parameter | Description |
|-----------|-------------|
| `stream_format` | `"pcm"` (default) or `"wav"` |
| `overrides` | Manual prosody overrides (`pitch_bias_st`, `gain_db`) |
| `abbreviation_config` | Custom abbreviation expansions |
| `lexicon_config` | Custom word-to-pronunciation overrides |

### V2 Only
| Parameter | Description |
|-----------|-------------|
| `repetition_penalty` | Orpheus repetition penalty |
| `speed` | Speech speed multiplier |
| `gain_db` | Output loudness |
| `pitch_bias_st` | Pitch shift |

### V3 Only
| Parameter | Description |
|-----------|-------------|
| `instructions` | Custom model instructions/prompts |
| `response_format` | `"pcm"` or `"pcm_s16le"` |

---

## Choosing the Right Endpoint

### Use V1 When:
- ✅ You want the best natural-sounding speech
- ✅ You need emotion-aware delivery
- ✅ You want automatic text processing
- ✅ You're building a consumer-facing TTS app

### Use V2 When:
- ✅ You want direct Orpheus control
- ✅ You have custom emotion tagging
- ✅ You need advanced Orpheus parameters
- ✅ You're building a developer tool

### Use V3 When:
- ✅ You want the latest model
- ✅ You need custom instructions
- ✅ You're building custom emotion logic
- ✅ You want minimal server overhead

---

## Performance Comparison

| Metric | V1 | V2 | V3 |
|--------|----|----|----|
| First Chunk Latency | ~300-500ms | ~200-400ms | ~150-300ms |
| Total Latency | ~2-5s | ~1-3s | ~1-2s |
| Server Processing | Heavy | Medium | Light |
| Sample Rate | 22050 Hz | 24000 Hz | 24000 Hz |

---

## Documentation Links

- [V1 Documentation](./api-docs.html)
- [V2 Documentation](./api-docs-v2.html)
- [V3 Documentation](./api-docs-v3.html)

---

## Examples

See the respective documentation pages for JavaScript and Python examples for each version.

---

## Support

For support, contact your account manager or check the [main README](../README.md).