# Veena3 TTS - Modal-native Spark TTS Service

**Status**: ✅ Modal-native (Django removed)

## Quick Start

### Local dev (tests)

```bash
cd /home/ubuntu/spark
source venv/bin/activate
pytest -q veena3modal/tests/unit
pytest -q veena3modal/tests --ignore=veena3modal/tests/modal_live
```

### Run on Modal

```bash
modal serve veena3modal/app.py
# or
modal deploy veena3modal/app.py
```

## API

- **Generate**: `POST /v1/tts/generate`
- **Health**: `GET /v1/tts/health`
- **Metrics**: `GET /v1/tts/metrics`

### Example (streaming WAV)

```bash
curl -X POST http://localhost:8000/v1/tts/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "text": "[excited] Hello! This is a streaming test.",
    "speaker": "lipakshi",
    "stream": true,
    "format": "wav"
  }' \
  -o output.wav
```

## Speakers + Emotions

### 12 Available Speakers (case-sensitive)

- `lipakshi`
- `vardan`
- `reet`
- `Nandini`
- `krishna`
- `anika`
- `adarsh`
- `Nilay`
- `Aarvi`
- `Asha`
- `Bittu`
- `Mira`

### 10 Emotions (Spark TTS bracket tags)

Use inline tags:

- `[angry]`, `[curious]`, `[excited]`, `[giggle]`, `[laughs harder]`
- `[laughs]`, `[screams]`, `[sighs]`, `[sings]`, `[whispers]`

Legacy `<laugh>`-style tags are also accepted and normalized.

## Auth

- **Dev**: `AUTH_BYPASS_MODE=true` bypasses key validation (enabled by default in `veena3modal/app.py` image env for testing).
- **Prod**: Provide an API key per request:
  - `X-API-Key: <key>`
  - or `Authorization: Bearer <key>`

## Repo Layout

- `veena3modal/`: Modal app + FastAPI API + inference/runtime code
- `external/`: vendored dependencies required at runtime
  - `external/sparktts/`: BiCodec tokenizer/decoder code
  - `external/AP-BWE/`: optional super-resolution (16kHz -> 48kHz)
- `modal_docs/`: Modal docs (kept in-repo)

## Model Weights

- Model weights are expected to live on a Modal Volume (see `veena3modal/app.py`).
- This repo may contain a local `models/` directory for convenience, but it is ignored by git.

## Progress Tracking

- Ongoing work log: `.cursor/progress.md`