# Project Overview

**SuperTonic3 OpenAI-Compatible Server** wraps [supertonic3](https://github.com/nicegram/nicegram-android) (ONNX-based)
to provide OpenAI-compatible TTS endpoints. Any OpenAI TTS client can use this for local, CPU-based text-to-speech with
31 languages and 10 built-in voices.

## Why This Exists

The official `pocket-tts` server was **not OpenAI API compatible**. This project ports that server to
`supertonic3`, which provides a simpler, lighter stack (ONNX runtime, no PyTorch) with 44100 Hz output and
multi-language support.

## Architecture

```
server.py                    # Entry point, CLI, starts Waitress
    └── app/__init__.py      # Flask app factory
        ├── app/routes.py    # API endpoints
        ├── app/config.py    # Environment config
        └── app/services/
            ├── tts.py       # TTSService: supertonic3 TTS engine wrapper
            └── audio.py     # Format conversion, streaming
```

## Key Files

| File                  | Purpose                                                          |
| --------------------- | ---------------------------------------------------------------- |
| `server.py`           | Entry point, CLI args, Waitress server                           |
| `app/routes.py`       | HTTP endpoints: `/`, `/health`, `/v1/voices`, `/v1/audio/speech` |
| `app/services/tts.py` | supertonic3 TTS engine loading, voice management, generation     |
| `app/config.py`       | Environment variables, path resolution                           |

## API Endpoints

| Endpoint           | Method | Purpose                             |
| ------------------ | ------ | ----------------------------------- |
| `/`                | GET    | Web UI                              |
| `/health`          | GET    | Health check for containers         |
| `/v1/voices`       | GET    | List voices                         |
| `/v1/audio/speech` | POST   | Generate speech (OpenAI-compatible) |

### Speech Request

```json
{
    "model": "tts-1",
    "input": "Text to speak",
    "voice": "M1",
    "response_format": "mp3",
    "stream": false,
    "lang": "en"
}
```

## CLI Arguments

| Argument            | Env Variable                           | Default   | Purpose                         |
| ------------------- | -------------------------------------- | --------- | ------------------------------- |
| `--host`            | `SUPERTONIC3_HOST`                     | `0.0.0.0` | Bind address                    |
| `--port`            | `SUPERTONIC3_PORT`                     | `7860`    | Port                            |
| `--voice`           | `SUPERTONIC3_VOICE`                    | `M1`      | Default voice                   |
| `--stream`          | `SUPERTONIC3_STREAM_DEFAULT`           | `false`   | Enable streaming by default     |
| `--text-preprocess` | `SUPERTONIC3_TEXT_PREPROCESS_DEFAULT`  | `false`   | Enable text preprocessing       |
| `--log-level`       | `SUPERTONIC3_LOG_LEVEL`                | `INFO`    | Log verbosity                   |

## Voices

10 built-in voices: M1-M5 (male), F1-F5 (female). No voice cloning.
Default voice: M1.

## Languages

31 supported languages via `lang` parameter in speech requests. See `SUPPORTED_LANGUAGES` in config.py.

## Development

```bash
# Install
pip install -r requirements.txt

# Run
python server.py --log-level DEBUG

# Test
curl http://localhost:7860/health
curl -X POST http://localhost:7860/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello", "voice": "M1"}' -o test.mp3
```

## Code Style

- Linter/formatter: `ruff` (config in `pyproject.toml`)
- Line length: 100
- Single quotes

## Deployment

- **Python**: `python server.py`
- **Docker**: `docker compose up -d`

## Key Differences from pocket-tts

| Feature          | pocket-tts              | supertonic3                  |
| ---------------- | ----------------------- | ---------------------------- |
| Inference engine | PyTorch + torchao       | ONNX Runtime                 |
| Sample rate      | 24000 Hz                | 44100 Hz                     |
| Voices           | 8 + voice cloning       | 10 (M1-M5, F1-F5), no clone |
| Languages        | Per-language models     | 31 languages, one model      |
| Quantization     | int8 support            | Not applicable               |
| Default port     | 49112                   | 7860                         |