From c1e2b5a5f029d3575f20502953b5a023b1855dac Mon Sep 17 00:00:00 2001 From: Richard R Date: Tue, 9 Jun 2026 10:27:33 -0600 Subject: [PATCH] docs(supertonic): add Supertonic TTS provider guide and update docs navigation Include documentation for configuring the Supertonic TTS provider. Update the main TTS providers list and sidebar to reference the new guide, ensuring users can easily find setup instructions for Supertonic. --- .../tts-provider-guides/supertonic.md | 68 +++++++++++++++++++ docs-site/docs/configure/tts-providers.md | 1 + docs-site/sidebars.ts | 1 + 3 files changed, 70 insertions(+) create mode 100644 docs-site/docs/configure/tts-provider-guides/supertonic.md 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',