diff --git a/docs-site/docs/configure/tts-provider-guides/supertonic.md b/docs-site/docs/configure/tts-provider-guides/supertonic.md new file mode 100644 index 0000000..498504a --- /dev/null +++ b/docs-site/docs/configure/tts-provider-guides/supertonic.md @@ -0,0 +1,68 @@ +--- +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) diff --git a/docs-site/docs/configure/tts-providers.md b/docs-site/docs/configure/tts-providers.md index fac1813..376e1dc 100644 --- a/docs-site/docs/configure/tts-providers.md +++ b/docs-site/docs/configure/tts-providers.md @@ -45,6 +45,7 @@ TTS requests originate from the **Next.js server**, not the browser. `API_BASE` - [Kokoro-FastAPI](./tts-provider-guides/kokoro-fastapi) - [KittenTTS-FastAPI](./tts-provider-guides/kitten-tts-fastapi) - [Orpheus-FastAPI](./tts-provider-guides/orpheus-fastapi) +- [Supertonic](./tts-provider-guides/supertonic) - [Replicate](./tts-provider-guides/replicate) - [DeepInfra](./tts-provider-guides/deepinfra) - [OpenAI](./tts-provider-guides/openai) diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts index fe5d1a3..30033c2 100644 --- a/docs-site/sidebars.ts +++ b/docs-site/sidebars.ts @@ -23,6 +23,7 @@ const sidebars: SidebarsConfig = { 'configure/tts-provider-guides/kokoro-fastapi', 'configure/tts-provider-guides/kitten-tts-fastapi', 'configure/tts-provider-guides/orpheus-fastapi', + 'configure/tts-provider-guides/supertonic', 'configure/tts-provider-guides/replicate', 'configure/tts-provider-guides/deepinfra', 'configure/tts-provider-guides/openai',