AGENTS.md

Project Overview

SuperTonic3 OpenAI-Compatible Server wraps supertonic3 (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

{
    "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

# 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