68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
---
|
||
title: Supertonic
|
||
---
|
||
|
||
Run [Supertonic](https://github.com/supertone-inc/supertonic-py) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider. Supertonic is a fast, on-device TTS engine that ships its own OpenAI-compatible HTTP server.
|
||
|
||
:::note No Docker image
|
||
Supertonic does not publish a Docker image — it installs as a Python package and runs as a local HTTP server. These instructions assume OpenReader itself runs in Docker (the common case); see [Running OpenReader directly on the host](#running-openreader-directly-on-the-host) if you don't.
|
||
:::
|
||
|
||
## Run Supertonic
|
||
|
||
Install with `pip` (or `pipx` for an isolated install) and start the server:
|
||
|
||
```bash
|
||
pipx install 'supertonic[serve]' # or: pip install 'supertonic[serve]'
|
||
supertonic serve # defaults; loopback only
|
||
```
|
||
|
||
The first run downloads the model (~400MB). Once it's up, the OpenAI-compatible endpoint is at `http://127.0.0.1:7788/v1/audio/speech` and interactive docs are at `http://127.0.0.1:7788/docs`.
|
||
|
||
- **Models:** `supertonic-3` (default) or `supertonic-2`.
|
||
- **Voices:** built-ins `M1`–`M5` and `F1`–`F5`, plus any custom voices you import. OpenReader discovers them automatically via the `/v1/styles` endpoint.
|
||
- **Audio format:** Supertonic emits `wav` by default; OpenReader transcodes it to mp3 transparently, so no extra configuration is needed.
|
||
|
||
## Connect to OpenReader
|
||
|
||
From a Docker container, your host machine is reachable at `host.docker.internal`, so the base URL is `http://host.docker.internal:7788/v1`. On Docker Desktop (macOS/Windows) this reaches the loopback-bound server above with no extra setup.
|
||
|
||
:::note Linux (native Docker Engine)
|
||
On native Linux Docker, `host.docker.internal` needs `--add-host=host.docker.internal:host-gateway` on the OpenReader container (or the equivalent `extra_hosts` entry in `docker-compose.yml`), and it routes to the host's bridge interface rather than loopback. Pick one:
|
||
|
||
- Run the OpenReader container with `--network host` (or `network_mode: host`), keep Supertonic on `--host 127.0.0.1`, and use `http://127.0.0.1:7788/v1` as the base URL.
|
||
- Or start Supertonic with `--host 0.0.0.0` so the bridge can reach it — keep it on a trusted network or behind a firewall.
|
||
:::
|
||
|
||
**Recommended (auth + admin): Settings → Admin → Shared providers**
|
||
|
||
1. Add a shared provider with type `custom-openai`.
|
||
2. Set base URL to `http://host.docker.internal:7788/v1`.
|
||
3. Leave API key blank — `supertonic serve` does not require one.
|
||
4. Set default model to `supertonic-3` (or `supertonic-2`).
|
||
|
||
**Legacy bootstrap seed (optional, first boot only):**
|
||
|
||
```env
|
||
API_BASE=http://host.docker.internal:7788/v1
|
||
```
|
||
|
||
**Or in-app via Settings → TTS Provider:**
|
||
|
||
1. Set provider to `Custom OpenAI-Like`.
|
||
2. Set `API_BASE` to `http://host.docker.internal:7788/v1`.
|
||
3. Leave `API_KEY` blank.
|
||
4. Choose model `supertonic-3` (or the model your deployment exposes).
|
||
|
||
See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
|
||
|
||
## Running OpenReader directly on the host
|
||
|
||
If OpenReader runs on the same machine (e.g. `pnpm dev`) rather than in Docker, skip `host.docker.internal` and use `http://127.0.0.1:7788/v1` as the base URL everywhere above.
|
||
|
||
## References
|
||
|
||
- [supertone-inc/supertonic-py](https://github.com/supertone-inc/supertonic-py)
|
||
- [Supported Languages](https://github.com/supertone-inc/supertonic-py#supported-languages)
|
||
- [TTS Providers](../tts-providers)
|
||
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)
|