danvics/openreader
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openreader/docs-site/docs/configure/tts-provider-guides/supertonic.md
Richard R c1e2b5a5f0 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.
2026-06-09 10:27:33 -06:00

3.5 KiB
Raw Permalink Blame History

title
Supertonic

Run Supertonic 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 if you don't. :::

Run Supertonic

Install with pip (or pipx for an isolated install) and start the server:

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):

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