diff --git a/docs-site/docs/configure/tts-provider-guides/custom-openai.md b/docs-site/docs/configure/tts-provider-guides/custom-openai.md deleted file mode 100644 index 132b44e..0000000 --- a/docs-site/docs/configure/tts-provider-guides/custom-openai.md +++ /dev/null @@ -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) diff --git a/docs-site/docs/configure/tts-provider-guides/deepinfra.md b/docs-site/docs/configure/tts-provider-guides/deepinfra.md index f7f3116..d1d6426 100644 --- a/docs-site/docs/configure/tts-provider-guides/deepinfra.md +++ b/docs-site/docs/configure/tts-provider-guides/deepinfra.md @@ -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) diff --git a/docs-site/docs/configure/tts-provider-guides/kitten-tts-fastapi.md b/docs-site/docs/configure/tts-provider-guides/kitten-tts-fastapi.md index d500e1c..427a41c 100644 --- a/docs-site/docs/configure/tts-provider-guides/kitten-tts-fastapi.md +++ b/docs-site/docs/configure/tts-provider-guides/kitten-tts-fastapi.md @@ -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 diff --git a/docs-site/docs/configure/tts-provider-guides/kokoro-fastapi.md b/docs-site/docs/configure/tts-provider-guides/kokoro-fastapi.md index 0d6d03c..10271ff 100644 --- a/docs-site/docs/configure/tts-provider-guides/kokoro-fastapi.md +++ b/docs-site/docs/configure/tts-provider-guides/kokoro-fastapi.md @@ -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 diff --git a/docs-site/docs/configure/tts-provider-guides/openai.md b/docs-site/docs/configure/tts-provider-guides/openai.md index 995c074..b5cf6fe 100644 --- a/docs-site/docs/configure/tts-provider-guides/openai.md +++ b/docs-site/docs/configure/tts-provider-guides/openai.md @@ -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) diff --git a/docs-site/docs/configure/tts-provider-guides/orpheus-fastapi.md b/docs-site/docs/configure/tts-provider-guides/orpheus-fastapi.md index ba4ab5c..fef9a7c 100644 --- a/docs-site/docs/configure/tts-provider-guides/orpheus-fastapi.md +++ b/docs-site/docs/configure/tts-provider-guides/orpheus-fastapi.md @@ -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 diff --git a/docs-site/docs/configure/tts-provider-guides/other.md b/docs-site/docs/configure/tts-provider-guides/other.md new file mode 100644 index 0000000..c509872 --- /dev/null +++ b/docs-site/docs/configure/tts-provider-guides/other.md @@ -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) diff --git a/docs-site/docs/configure/tts-providers.md b/docs-site/docs/configure/tts-providers.md index 059ef80..01783e6 100644 --- a/docs-site/docs/configure/tts-providers.md +++ b/docs-site/docs/configure/tts-providers.md @@ -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 - - +- **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`. - - +## 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. - - - - -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. - - - - -## 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) diff --git a/docs-site/docs/introduction.md b/docs-site/docs/introduction.md index 2dc94ad..4187ebf 100644 --- a/docs-site/docs/introduction.md +++ b/docs-site/docs/introduction.md @@ -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 diff --git a/docs-site/docs/reference/environment-variables.md b/docs-site/docs/reference/environment-variables.md index daef2bd..202a7bb 100644 --- a/docs-site/docs/reference/environment-variables.md +++ b/docs-site/docs/reference/environment-variables.md @@ -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 diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts index 1e650bd..a0bea2e 100644 --- a/docs-site/sidebars.ts +++ b/docs-site/sidebars.ts @@ -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', ], }, {