danvics/openreader
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: refactor TTS provider setup documentation

Browse source
This commit is contained in:
Richard R 2026-03-19 10:26:05 -06:00
parent 1deb8c21f7
commit 3c37b0c59e
11 changed files with 165 additions and 197 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
docs-site/docs/configure/tts-provider-guides/custom-openai.md
View file

@ -1,42 +0,0 @@
---
title: Custom OpenAI
---
Use any custom OpenAI-compatible TTS service with OpenReader.
Use this integration when your endpoint is not directly covered by built-in dropdown defaults.
Known compatible examples include Kokoro-FastAPI, KittenTTS-FastAPI, and Orpheus-FastAPI.
## Provider
- Provider: `Custom OpenAI-Like`
- `API_BASE`: required (your service base URL)
- `API_KEY`: set if required by your service
Custom providers should expose:
- `GET /v1/audio/voices`
- `POST /v1/audio/speech`
## OpenReader setup
1. In OpenReader Settings, choose provider `Custom OpenAI-Like`.
2. Set `API_BASE` to your service base URL (typically ending with `/v1`).
3. Set `API_KEY` if your service requires authentication.
4. Choose a model and voice supported by your backend.
## Notes
:::warning Compatibility required
Custom providers must implement OpenAI-compatible TTS endpoints, including `GET /v1/audio/voices` and `POST /v1/audio/speech`.
:::
:::info Voice troubleshooting
If voices do not load, verify the `/v1/audio/voices` response shape and that the endpoint is reachable from the OpenReader server.
:::
## References
- [TTS Providers](../tts-providers)
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

39
docs-site/docs/configure/tts-provider-guides/deepinfra.md
View file

@ -1,33 +1,36 @@
---
title: Deepinfra
title: DeepInfra
---
Use Deepinfra as a hosted OpenAI-compatible TTS provider.
Use DeepInfra's hosted TTS models as your provider.
## Provider
## Setup
- Provider: `Deepinfra`
- Default endpoint: `https://api.deepinfra.com/v1/openai` (auto-filled)
- `API_KEY`: required for authenticated DeepInfra usage
**Environment variables (recommended for deployment):**
## OpenReader setup
```env
API_BASE=https://api.deepinfra.com/v1/openai
API_KEY=your-deepinfra-key
NEXT_PUBLIC_DEFAULT_TTS_PROVIDER=deepinfra
```
1. In OpenReader Settings, choose provider `Deepinfra`.
2. Keep the default `API_BASE`.
3. Set `API_KEY`.
4. Choose your model and voice.
**Or in-app via Settings → TTS Provider:**
1. Set provider to `Deepinfra`.
2. The base URL is pre-filled, no changes needed.
3. Enter your `API_KEY`.
4. Choose a model and voice.
Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
## Notes
:::tip Built-in endpoint
`Deepinfra` is a built-in provider, so OpenReader auto-fills the default `API_BASE`.
:::
:::info Model support
DeepInfra exposes multiple TTS models, including Kokoro-family options.
:::
- Available models include `hexgrad/Kokoro-82M` and `canopylabs/orpheus-3b-0.1-ft`.
- Without an API key, only the free-tier model (`hexgrad/Kokoro-82M`) is shown in the dropdown.
- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
## References
- [DeepInfra TTS models](https://deepinfra.com/models/text-to-speech)
- [TTS Providers](../tts-providers)
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

38
docs-site/docs/configure/tts-provider-guides/kitten-tts-fastapi.md
View file

@ -2,16 +2,9 @@
title: KittenTTS-FastAPI
---
Use [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI) as an OpenAI-compatible TTS backend for OpenReader.
Run [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider. Lightweight and CPU-friendly.
## Provider
- Provider: `Custom OpenAI-Like`
- Typical model: `kitten-tts`
- `API_BASE`: required (usually your KittenTTS URL ending with `/v1`)
- `API_KEY`: set only if your deployment requires one
## Run KittenTTS (CPU)
## Run KittenTTS
```bash
docker run -it --rm \
@ -21,23 +14,24 @@ docker run -it --rm \
ghcr.io/richardr1126/kittentts-fastapi-cpu
```
## OpenReader setup
## Connect to OpenReader
1. Start your KittenTTS-FastAPI server.
2. In OpenReader Settings, choose provider `Custom OpenAI-Like`.
3. Set `API_BASE` to your KittenTTS base URL (typically ending with `/v1`).
4. Set `API_KEY` only if your deployment requires one.
5. Choose model `kitten-tts` (or another model exposed by your deployment).
**Environment variables (recommended for deployment):**
## Notes
```env
API_BASE=http://kittentts-fastapi:8005/v1
```
:::info OpenAI-compatible API
OpenReader expects OpenAI-compatible audio endpoints when using KittenTTS through `Custom OpenAI-Like`.
:::
> Use `kittentts-fastapi` if that's the container name, or `host.docker.internal` if not.
:::tip Endpoint shape
Use an `API_BASE` that points at the KittenTTS API root (typically ending with `/v1`).
:::
**Or in-app via Settings → TTS Provider:**
1. Set provider to `Custom OpenAI-Like`.
2. Set `API_BASE` to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
3. Leave `API_KEY` blank unless your deployment requires one.
4. Choose model `kitten-tts` (or the model your deployment exposes).
Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
## References

38
docs-site/docs/configure/tts-provider-guides/kokoro-fastapi.md
View file

@ -2,20 +2,15 @@
title: Kokoro-FastAPI
---
You can run the Kokoro TTS API server directly with Docker.
Run [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
:::warning
For Kokoro issues and support, use the upstream repository: [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI).
:::
## Provider
## Run Kokoro
- Provider: `Custom OpenAI-Like`
- Typical model: `Kokoro`
- `API_BASE`: required (typically your Kokoro URL ending with `/v1`)
- `API_KEY`: set only if your deployment requires one
## Run Kokoro (CPU)
**CPU:**
```bash
docker run --name kokoro-tts \
@ -32,7 +27,7 @@ docker run --name kokoro-tts \
ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
```
## Run Kokoro (GPU)
**GPU (NVIDIA):**
```bash
docker run --name kokoro-tts \
@ -47,19 +42,24 @@ docker run --name kokoro-tts \
ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.4
```
## OpenReader setup
## Connect to OpenReader
1. Start Kokoro using either the CPU or GPU image.
2. In OpenReader Settings, choose provider `Custom OpenAI-Like`.
3. Set `API_BASE` to your Kokoro endpoint (for Docker Compose, commonly `http://kokoro-tts:8880/v1`).
4. Set `API_KEY` only if your deployment requires one.
5. Choose model `Kokoro`.
**Environment variables (recommended for deployment):**
## Notes
```env
API_BASE=http://kokoro-tts:8880/v1
```
:::tip Runtime guidance
GPU mode requires NVIDIA Docker support and is best on NVIDIA hardware. CPU mode is a good default on Apple Silicon and modern x86 CPUs.
:::
> Use `kokoro-tts` if that's the container name, or `host.docker.internal` if not.
**Or in-app via Settings → TTS Provider:**
1. Set provider to `Custom OpenAI-Like`.
2. Set `API_BASE` to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
3. Leave `API_KEY` blank unless your deployment requires one.
4. Choose model `Kokoro`.
Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
## References

36
docs-site/docs/configure/tts-provider-guides/openai.md
View file

@ -2,32 +2,34 @@
title: OpenAI
---
Use OpenAI directly as an OpenAI-compatible TTS provider.
Use the OpenAI TTS API as your provider.
## Provider
## Setup
- Provider: `OpenAI`
- Default endpoint: `https://api.openai.com/v1` (auto-filled)
- `API_KEY`: required for OpenAI access
**Environment variables (recommended for deployment):**
## OpenReader setup
```env
API_BASE=https://api.openai.com/v1
API_KEY=sk-...
NEXT_PUBLIC_DEFAULT_TTS_PROVIDER=openai
```
1. In OpenReader Settings, choose provider `OpenAI`.
2. Keep the default `API_BASE`.
3. Set `API_KEY`.
4. Choose your model and voice.
**Or in-app via Settings → TTS Provider:**
1. Set provider to `OpenAI`.
2. The base URL is pre-filled, no changes needed.
3. Enter your `API_KEY`.
4. Choose a model and voice.
Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
## Notes
:::tip Built-in endpoint
`OpenAI` is a built-in provider, so OpenReader auto-fills the default `API_BASE`.
:::
:::info Server-side requests
OpenReader sends TTS requests from the server runtime, not directly from the browser.
:::
- Models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
## References
- [OpenAI TTS pricing](https://platform.openai.com/docs/pricing#transcription-and-speech)
- [TTS Providers](../tts-providers)
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

36
docs-site/docs/configure/tts-provider-guides/orpheus-fastapi.md
View file

@ -2,32 +2,30 @@
title: Orpheus-FastAPI
---
Use Orpheus-FastAPI as an OpenAI-compatible TTS backend for OpenReader.
Run [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
## Provider
## Run Orpheus
- Provider: `Custom OpenAI-Like`
- Typical model: `Orpheus`
- `API_BASE`: required (usually your Orpheus URL ending with `/v1`)
- `API_KEY`: set only if your deployment requires one
Refer to the upstream repository for Docker instructions: [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
## OpenReader setup
## Connect to OpenReader
1. Start your Orpheus-FastAPI server.
2. In OpenReader Settings, choose provider `Custom OpenAI-Like`.
3. Set `API_BASE` to your Orpheus base URL (typically ending with `/v1`).
4. Set `API_KEY` only if your Orpheus deployment requires one.
5. Choose model `Orpheus` (or another model exposed by your deployment).
**Environment variables (recommended for deployment):**
## Notes
```env
API_BASE=http://orpheus:8000/v1
```
:::info OpenAI-compatible API
OpenReader expects OpenAI-compatible audio endpoints when using Orpheus through `Custom OpenAI-Like`.
:::
> Use the container name if that's how it's named, or `host.docker.internal` if not.
:::tip Endpoint shape
Use an `API_BASE` that points at the Orpheus API root (typically ending with `/v1`).
:::
**Or in-app via Settings → TTS Provider:**
1. Set provider to `Custom OpenAI-Like`.
2. Set `API_BASE` to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
3. Leave `API_KEY` blank unless your deployment requires one.
4. Choose model `Orpheus` (or the model your deployment exposes).
Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
## References

45
docs-site/docs/configure/tts-provider-guides/other.md Normal file
View file

@ -0,0 +1,45 @@
---
title: Other
---
Use any OpenAI-compatible TTS service with OpenReader, including self-hosted servers not covered by a dedicated guide.
## Requirements
Your service must expose these endpoints:
- `GET /v1/audio/voices`
- `POST /v1/audio/speech`
Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi).
## Setup
**Environment variables (recommended for deployment):**
```env
API_BASE=http://your-tts-server/v1
API_KEY=optional-key-if-required
```
**Or in-app via Settings → TTS Provider:**
1. Set provider to `Custom OpenAI-Like`.
2. Set `API_BASE` to your service's base URL (typically ending in `/v1`).
3. Set `API_KEY` if your service requires authentication.
4. Choose a model and voice supported by your backend.
Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
:::warning TTS requests are server-side
`API_BASE` must be reachable from the **Next.js server**, not just the browser. In Docker, use container names or `host.docker.internal`.
:::
## Troubleshooting
If voices don't load, check that `/v1/audio/voices` is reachable from the server and returns a valid response shape.
## References
- [TTS Providers](../tts-providers)
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

72
docs-site/docs/configure/tts-providers.md
View file

@ -2,79 +2,45 @@
title: TTS Providers
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
OpenReader routes all TTS requests through the Next.js server to an OpenAI-compatible API. You choose your provider and credentials in one of two places:
OpenReader supports OpenAI-compatible TTS providers through a common API shape.
**Environment variables**: set in your `.env` or `docker-compose.yml` as server-level defaults. Applied when the user has no saved Settings.
:::tip
If you are running a self-hosted TTS server (Kokoro/KittenTTS/Orpheus/etc.), use **Custom OpenAI-Like** in Settings.
**Settings modal** (Settings > TTS Provider): stored in the browser and sent with every TTS request. **Overrides env vars.**
:::note
Set env vars as deployment-level defaults. Users (or you, in a single-user setup) can then change the provider, base URL, and API key from the Settings modal without redeploying. Clearing the Settings fields falls back to the env var defaults.
:::
## Quick Setup by Provider
## Providers
<Tabs groupId="tts-provider-setup">
<TabItem value="openai" label="OpenAI" default>
- **OpenAI**: Cloud. Base URL pre-filled (`https://api.openai.com/v1`). API key required.
- **Deepinfra**: Cloud. Base URL pre-filled (`https://api.deepinfra.com/v1/openai`). API key required.
- **Custom OpenAI-Like**: Self-hosted or any custom endpoint. `API_BASE` must be set manually (typically ending in `/v1`). API key optional.
1. In Settings, choose provider: `OpenAI`.
2. Keep the default `API_BASE` (auto-filled).
3. Set `API_KEY` to your OpenAI key.
4. Choose model/voice.
For `OpenAI` and `Deepinfra` you only need to supply an API key. For `Custom OpenAI-Like` you must also set `API_BASE`.
</TabItem>
<TabItem value="deepinfra" label="DeepInfra">
## Custom provider requirements
1. In Settings, choose provider: `Deepinfra`.
2. Keep the default `API_BASE` (auto-filled).
3. Set `API_KEY` to your DeepInfra key.
4. Choose model/voice.
</TabItem>
<TabItem value="custom" label="Custom OpenAI-Like">
1. In Settings, choose provider: `Custom OpenAI-Like`.
2. Set `API_BASE` to your endpoint (example: `http://host.docker.internal:8880/v1`).
3. Set `API_KEY` if your provider requires one.
4. Choose model/voice.
</TabItem>
</Tabs>
## Provider Dropdown Behavior
In Settings, provider options include:
- `OpenAI`
- `Deepinfra`
- `Custom OpenAI-Like` (Kokoro, KittenTTS-FastAPI, Orpheus, and other OpenAI-compatible endpoints)
`API_BASE` guidance:
- `OpenAI` and `Deepinfra` auto-fill default endpoints.
- `Custom OpenAI-Like` requires setting `API_BASE` manually.
:::info OpenAI-Compatible API Shape
Custom providers should expose:
Self-hosted or custom providers must expose OpenAI-compatible audio endpoints:
- `GET /v1/audio/voices`
- `POST /v1/audio/speech`
:::warning TTS requests are server-side
TTS requests originate from the **Next.js server**, not the browser. `API_BASE` must be reachable from the server runtime. In Docker, use container names or `host.docker.internal` rather than `localhost`.
:::
:::warning Server-Reachable API Base
TTS requests are sent from the Next.js server, not directly from the browser. `API_BASE` must be reachable from the server runtime.
:::
## Provider Guides
## Provider guides
- [Kokoro-FastAPI](./tts-provider-guides/kokoro-fastapi)
- [KittenTTS-FastAPI](./tts-provider-guides/kitten-tts-fastapi)
- [Orpheus-FastAPI](./tts-provider-guides/orpheus-fastapi)
- [DeepInfra](./tts-provider-guides/deepinfra)
- [OpenAI](./tts-provider-guides/openai)
- [Custom OpenAI-Like](./tts-provider-guides/custom-openai)
- [Other](./tts-provider-guides/other)
## Related Configuration
## Related
- [TTS Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
- [TTS Rate Limiting](./tts-rate-limiting)
- [Auth](./auth)

2
docs-site/docs/introduction.md
View file

@ -32,7 +32,7 @@ It supports multiple TTS providers including OpenAI, DeepInfra, and custom OpenA
- 🗂️ **Flexible Storage and Database Modes** with embedded defaults or external S3/Postgres
- 🚀 **Production-ready Server Behavior** with TTS caching/retries/rate limits and startup migrations
- 🎨 **Customizable Experience**
- Theme, TTS, and document handling controls
- 13 built-in themes (light and dark palettes), TTS, and document handling controls
## 🧭 Key Docs

12
docs-site/docs/reference/environment-variables.md
View file

@ -60,18 +60,20 @@ This is the single reference page for OpenReader environment variables.
### API_BASE
Base URL for OpenAI-compatible TTS API requests.
Server-level default base URL for OpenAI-compatible TTS API requests.
- Example: `http://host.docker.internal:8880/v1`
- Can be overridden per request from UI settings
- Used when no `API_BASE` is set in the user's Settings modal
- If the user sets `API_BASE` in **Settings → TTS Provider**, that value takes precedence
- Related docs: [TTS Providers](../configure/tts-providers)
### API_KEY
Default API key for TTS provider requests.
Server-level default API key for TTS provider requests.
- Example: `none` or your provider token
- Can be overridden by request headers from app settings
- Example: your provider token, or omit if the provider doesn't require auth
- Used when no `API_KEY` is set in the user's Settings modal
- If the user sets `API_KEY` in **Settings → TTS Provider**, that value takes precedence
- Related docs: [TTS Providers](../configure/tts-providers)
### TTS_CACHE_MAX_SIZE_BYTES

2
docs-site/sidebars.ts
View file

@ -25,7 +25,7 @@ const sidebars: SidebarsConfig = {
'configure/tts-provider-guides/orpheus-fastapi',
'configure/tts-provider-guides/deepinfra',
'configure/tts-provider-guides/openai',
'configure/tts-provider-guides/custom-openai',
'configure/tts-provider-guides/other',
],
},
{