README.md

---
title: Parler TTS API
emoji: 🎙️
colorFrom: blue
colorTo: green
sdk: docker
app_file: api.py
python_version: 3.10
---

# Indic Parler-TTS API

FastAPI endpoint for Urdu Text-to-Speech using [ai4bharat/indic-parler-tts](https://huggingface.co/ai4bharat/indic-parler-tts).

## API Endpoints

### Health Check
```
GET /
```
Returns model status and available speakers.

**Response:**
```json
{
  "status": "ok",
  "model": "Indic Parler-TTS",
  "speakers": ["Divya", "Rani", "Rohit", "Aman", "Generic Female", "Generic Male"],
  "sample_rate": 24000
}
```

### Generate Speech
```
POST /tts
```

**Request Body:**
```json
{
  "text": "السلام علیکم، میرا نام اردو ٹی ٹی ایس ہے۔",
  "speaker": "Divya",
  "pitch": "Moderate",
  "rate": "Moderate",
  "temperature": 0.8,
  "do_sample": true
}
```

**Parameters:**
- `text` (string, required): Urdu text to synthesize
- `speaker` (string, optional): Speaker name. Options: `Divya`, `Rani`, `Rohit`, `Aman`, `Generic Female`, `Generic Male`. Default: `Divya`
- `pitch` (string, optional): Voice pitch. Options: `High`, `Moderate`, `Low`. Default: `Moderate`
- `rate` (string, optional): Speaking rate. Options: `Slow`, `Moderate`, `Fast`. Default: `Moderate`
- `temperature` (float, optional): Sampling temperature (0.1-2.0). Default: `0.8`
- `do_sample` (boolean, optional): Use sampling vs greedy decoding. Default: `true`

**Response:**
- WAV audio file (audio/wav)

### Get Available Speakers
```
GET /speakers
```

**Response:**
```json
{
  "speakers": ["Divya", "Rani", "Rohit", "Aman", "Generic Female", "Generic Male"]
}
```

## Example Usage

### cURL
```bash
curl -X POST http://localhost:7860/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "السلام علیکم",
    "speaker": "Divya",
    "pitch": "Moderate",
    "rate": "Moderate"
  }' \
  --output speech.wav
```

### Python
```python
import requests
import json

url = "http://localhost:7860/tts"
payload = {
    "text": "السلام علیکم، میرا نام اردو ٹی ٹی ایس ہے۔",
    "speaker": "Divya",
    "pitch": "Moderate",
    "rate": "Moderate",
    "temperature": 0.8,
    "do_sample": True
}

response = requests.post(url, json=payload)
if response.status_code == 200:
    with open("speech.wav", "wb") as f:
        f.write(response.content)
    print("Audio saved!")
else:
    print(f"Error: {response.status_code}")
    print(response.text)
```

## Running Locally

### With Docker
```bash
docker build -t parler-tts-api .
docker run -p 7860:7860 --gpus all parler-tts-api
```

### Without Docker
```bash
python3 -m venv venv
source venv/bin/activate
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt
pip install uvicorn[standard]
python api.py
```

Then visit `http://localhost:7860/docs` for interactive API documentation.

## Environment Variables

For HF Spaces deployment, set the following secret:
- `HF_TOKEN`: Your Hugging Face API token (required for gated model access)

## Technical Details

- **Model**: Indic Parler-TTS (multi-speaker, multi-language)
- **Language**: Urdu (auto-detected from script)
- **Sample Rate**: 24 kHz
- **Audio Format**: WAV (16-bit PCM)
- **Framework**: FastAPI + PyTorch
- **Deployment**: HF Spaces Docker runtime

### Quality Notes
- Language is auto-detected from Urdu script — do NOT mention language in voice descriptions
- Named speakers (Divya, Rohit, etc.) provide consistent voices
- Same random seed used across sentences for voice consistency within a generation
- Text cleaning removes Latin/English characters to prevent language mixing